内容
# TiDB Cloud Zero MCP 服务器
给任何 AI 代理一个持久的 MySQL 数据库，通过 [模型上下文协议](https://modelcontextprotocol.io)。
**零配置** — 服务器在首次使用时自动配置一个免费的 [TiDB Cloud Zero](https://zero.tidbcloud.com) 实例。无需注册，无需 API 密钥，无需凭证。只需运行它。
## 工作原理
```
┌─────────────┐ MCP ┌──────────────┐ HTTPS ┌─────────────────┐
│ AI 代理 │◄────────────►│ MCP 服务器 │◄────────────►│ TiDB Cloud Zero │
│ (Claude, │ stdio/http │ (此仓库) │ /v1beta/sql │ (免费 MySQL) │
│ Cursor) │ │ │ 纯 HTTP │ │
└─────────────┘ └──────────────┘ └─────────────────┘
```
在首次查询时，服务器调用 `POST https://zero.tidbapi.com/v1alpha1/instances` 以创建免费数据库，然后使用 [TiDB Serverless HTTP API](https://github.com/tidbcloud/serverless-js) 进行所有 SQL 查询 — 纯 HTTPS，无需 MySQL 驱动，无需持久连接。
实例凭证缓存在本地 (`~/.tidb-cloud-zero-mcp/instance.json`) 并在过期前重用。
## 快速开始
```bash
git clone https://github.com/siddontang/tidb-cloud-zero-mcp.git
cd tidb-cloud-zero-mcp
uv run server.py
```
就这样。无需环境变量。首次查询会自动配置数据库。
### 连接到 Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"tidb": {
"command": "uv",
"args": ["run", "--project", "/path/to/tidb-cloud-zero-mcp", "server.py"]
}
}
}
```
### 连接到 Claude Code
```bash
claude mcp add tidb -- uv run --project /path/to/tidb-cloud-zero-mcp server.py
```
### 连接到 Cursor / Windsurf
将以下内容添加到您的 MCP 设置：
```json
{
"tidb": {
"command": "uv",
"args": ["run", "--project", "/path/to/tidb-cloud-zero-mcp", "server.py"]
}
}
```
### HTTP 传输
```bash
uv run server.py --transport http
# 在 http://localhost:8000/mcp 连接
```
## 自带数据库（可选）
如果您已经有一个 TiDB Cloud 实例，请设置 `TIDB_URL`:
```bash
export TIDB_URL="mysql://user:password@host/database"
uv run server.py
```
或单独设置变量：
```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"
```
## 工具
| 工具 | 描述 |
|------|-------------|
| `query` | 运行 SELECT / SHOW / DESCRIBE / EXPLAIN |
| `execute` | 运行 CREATE / INSERT / UPDATE / DELETE / ALTER |
| `batch_execute` | 顺序运行多个 SQL 语句 |
| `list_tables` | 列出所有表及其行数 |
| `describe_table` | 获取表架构 |
| `get_database_info` | 数据库信息、版本和实例状态 |
## 示例交互
连接后，询问您的 AI 代理：
- *"创建一张用户表并添加一些示例数据"*
- *"显示数据库中的所有表"*
- *"分析订单表中的数据"*
- *"编写一个查询语句以按收入查找前 10 名客户"*
代理使用 MCP 工具直接与 TiDB Cloud Zero 交互 — 无需配置。
## 架构
每个 SQL 查询都是对 TiDB 的 Serverless HTTP API 的单个 HTTP POST 请求：
```
POST https://http-{host}/v1beta/sql
Authorization: Basic {base64(user:pass)}
TiDB-Database: {database}
Content-Type: application/json
{"query": "SELECT * FROM users"}
```
这意味着：
- **无需 MySQL 驱动** — 任何地方都可以使用 HTTPS
- **无需连接管理** — 无状态，每个查询都是独立的
- **兼容边缘** — 在无服务器函数和边缘工作器中运行
- **自动配置** — 通过 Zero API 在首次使用时创建数据库
## 为什么选择 TiDB Cloud Zero？
| 功能 | 优势 |
|---------|---------|
| **零注册** | 无需账户，无需信用卡 — 直接使用 |
| **MySQL 兼容** | 与每个工具、ORM 和语言兼容 |
| **无服务器** | 无需配置，无需维护 |
| **HTTP API** | 无需驱动，纯 HTTPS |
| **向量搜索** | 将嵌入式数据与关系数据一起存储 |
| **可丢弃** | 72 小时实例用于测试和演示 |
## 开发
```bash
uv sync # 安装依赖
uv run mcp dev server.py # 使用 MCP Inspector 测试
uv run server.py --transport http # 运行 HTTP 服务器
```
## 许可证
MIT
---
**试用 TiDB Cloud:** [免费试用](https://tidbcloud.com/free-trial/?utm_source=sales_bdm&utm_medium=sales&utm_content=Siddon) • [基础 101](https://www.pingcap.com/essential101/?utm_source=sales_bdm&utm_medium=sales&utm_content=Siddon) • [创业计划](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)
