Content
# TiDB Cloud Zero MCP Server
Give any AI agent a persistent MySQL database through the [Model Context Protocol](https://modelcontextprotocol.io).
**Zero config** — the server automatically provisions a free [TiDB Cloud Zero](https://zero.tidbcloud.com) instance on first use. No signup, no API keys, no credentials. Just run it.
## How It Works
```
┌─────────────┐ MCP ┌──────────────┐ HTTPS ┌─────────────────┐
│ AI Agent │◄────────────►│ MCP Server │◄────────────►│ TiDB Cloud Zero │
│ (Claude, │ stdio/http │ (this repo) │ /v1beta/sql │ (free MySQL) │
│ Cursor) │ │ │ pure HTTP │ │
└─────────────┘ └──────────────┘ └─────────────────┘
```
On first query, the server calls `POST https://zero.tidbapi.com/v1alpha1/instances` to create a free database, then uses the [TiDB Serverless HTTP API](https://github.com/tidbcloud/serverless-js) for all SQL — pure HTTPS, no MySQL driver, no persistent connections.
The instance credentials are cached locally (`~/.tidb-cloud-zero-mcp/instance.json`) and reused until expiry.
## Quick Start
```bash
git clone https://github.com/siddontang/tidb-cloud-zero-mcp.git
cd tidb-cloud-zero-mcp
uv run server.py
```
That's it. No environment variables needed. The first query auto-provisions a database.
### Connect to Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"tidb": {
"command": "uv",
"args": ["run", "--project", "/path/to/tidb-cloud-zero-mcp", "server.py"]
}
}
}
```
### Connect to Claude Code
```bash
claude mcp add tidb -- uv run --project /path/to/tidb-cloud-zero-mcp server.py
```
### Connect to Cursor / Windsurf
Add to your MCP settings:
```json
{
"tidb": {
"command": "uv",
"args": ["run", "--project", "/path/to/tidb-cloud-zero-mcp", "server.py"]
}
}
```
### HTTP Transport
```bash
uv run server.py --transport http
# Connect at http://localhost:8000/mcp
```
## Bring Your Own Database (Optional)
If you already have a TiDB Cloud instance, set `TIDB_URL`:
```bash
export TIDB_URL="mysql://user:password@host/database"
uv run server.py
```
Or individual variables:
```bash
export TIDB_HOST="gateway01.us-west-2.prod.aws.tidbcloud.com"
export TIDB_USERNAME="your_user"
export TIDB_PASSWORD="your_password"
export TIDB_DATABASE="test"
```
## Tools
| Tool | Description |
|------|-------------|
| `query` | Run SELECT / SHOW / DESCRIBE / EXPLAIN |
| `execute` | Run CREATE / INSERT / UPDATE / DELETE / ALTER |
| `batch_execute` | Run multiple SQL statements sequentially |
| `list_tables` | List all tables with row counts |
| `describe_table` | Get table schema |
| `get_database_info` | Database info, version, and instance status |
## Example Interactions
Once connected, ask your AI agent:
- *"Create a users table and add some sample data"*
- *"Show me all tables in the database"*
- *"Analyze the data in the orders table"*
- *"Write a query to find the top 10 customers by revenue"*
The agent uses MCP tools to interact with TiDB Cloud Zero directly — no configuration needed.
## Architecture
Every SQL query is a single HTTP POST to TiDB's Serverless HTTP API:
```
POST https://http-{host}/v1beta/sql
Authorization: Basic {base64(user:pass)}
TiDB-Database: {database}
Content-Type: application/json
{"query": "SELECT * FROM users"}
```
This means:
- **No MySQL driver** — works anywhere with HTTPS
- **No connection management** — stateless, each query is independent
- **Edge-compatible** — runs in serverless functions and edge workers
- **Auto-provisioning** — database created on first use via Zero API
## Why TiDB Cloud Zero?
| Feature | Benefit |
|---------|---------|
| **Zero signup** | No account, no credit card — just use it |
| **MySQL compatible** | Works with every tool, ORM, and language |
| **Serverless** | No provisioning, no maintenance |
| **HTTP API** | No drivers needed, pure HTTPS |
| **Vector Search** | Store embeddings alongside relational data |
| **Disposable** | 72-hour instances for testing and demos |
## Development
```bash
uv sync # Install dependencies
uv run mcp dev server.py # Test with MCP Inspector
uv run server.py --transport http # Run HTTP server
```
## License
MIT
---
**Try TiDB Cloud:** [Free Trial](https://tidbcloud.com/free-trial/?utm_source=sales_bdm&utm_medium=sales&utm_content=Siddon) • [Essential 101](https://www.pingcap.com/essential101/?utm_source=sales_bdm&utm_medium=sales&utm_content=Siddon) • [Startup Program](https://www.pingcap.com/tidb-cloud-startup-program/?utm_source=sales_bdm&utm_medium=sales&utm_content=Siddon) • [TiDB Cloud AI](https://www.pingcap.com/ai?utm_source=sales_bdm&utm_medium=sales&utm_content=Siddon)
