TiDB Cloud Zero MCP Server

TiDB Cloud Zero MCP Server

Give any AI agent a persistent MySQL database through the Model Context Protocol.

Zero config — the server automatically provisions a free TiDB Cloud Zero 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 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

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:

{
  "mcpServers": {
    "tidb": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/tidb-cloud-zero-mcp", "server.py"]
    }
  }
}

Connect to Claude Code

claude mcp add tidb -- uv run --project /path/to/tidb-cloud-zero-mcp server.py

Connect to Cursor / Windsurf

Add to your MCP settings:

{
  "tidb": {
    "command": "uv",
    "args": ["run", "--project", "/path/to/tidb-cloud-zero-mcp", "server.py"]
  }
}

HTTP Transport

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:

export TIDB_URL="mysql://user:password@host/database"
uv run server.py

Or individual variables:

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

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 • Essential 101 • Startup Program • TiDB Cloud AI