MCP Server Tidbcloud

TiDB云MCP服务器

MCP（模型上下文协议）服务器，使LLM能够通过自然语言与TiDB Cloud交互。

特性

• 群集管理：创建、列出、更新和删除TiDB Cloud无服务器集群
• 分行管理：为集群创建、列出、获取和删除分支
• 数据库操作：执行SQL查询并管理数据库架构
• 区域发现：列出可用于创建集群的区域
• 异步操作支持：通过状态检查正确处理长时间运行的操作
• 两种运输方式:

- 标准：Claude Desktop的本地服务器（env vars中的API密钥） - 流式HTTP：托管部署的远程服务器（标头中的API密钥）

先决条件

• Node.js 22或更高版本
• pnpm包管理器
• 具有API访问权限的TiDB云帐户

获取API密钥

1. 登录到 TiDB云控制台
2. 点击左侧边栏中的组织名称
3. 引导到 组织设置 → API密钥
4. 点击 创建API密钥
5. 复制这两个 公钥 和 私钥 （安全保存私钥，不会再次显示）

安装

# Clone the repository
git clone https://github.com/tidbcloud/mcp-server-tidbcloud.git
cd mcp-server-tidbcloud

# Install dependencies
pnpm install

# Build the project
pnpm build

使用Claude Desktop

有两种方法可以将此MCP服务器与Claude Desktop一起使用：

选项1:本地服务器（stdio）--推荐

使用Claude Desktop中配置的API密钥在本地运行服务器。最适合开发或需要完全控制时。

将以下内容添加到您的Claude Desktop配置文件中(claude_desktop_config.json):

{
  "mcpServers": {
    "tidbcloud": {
      "command": "node",
      "args": ["/path/to/mcp-server-tidbcloud/packages/server/dist/index.js"],
      "env": {
        "TIDB_CLOUD_PUBLIC_KEY": "your-public-key",
        "TIDB_CLOUD_PRIVATE_KEY": "your-private-key"
      }
    }
  }
}

环境变量（本地服务器）：

选项2：远程服务器

使用连接到托管的MCP服务器 mcp-remote.您的API密钥是通过头传递的-它们不存储在服务器上。

Claude桌面配置：

{
  "mcpServers": {
    "TiDB Cloud": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp-server-tidbcloud.workers.dev/mcp",
        "--header", "X-TiDB-API-Public-Key:${TIDB_CLOUD_PUBLIC_KEY}",
        "--header", "X-TiDB-API-Private-Key:${TIDB_CLOUD_PRIVATE_KEY}"
      ],
      "env": {
        "TIDB_CLOUD_PUBLIC_KEY": "your-public-key",
        "TIDB_CLOUD_PRIVATE_KEY": "your-private-key"
      }
    }
  }
}

使用数据库凭据（用于SQL操作）：

使用数据库工具(show_databases, db_query, db_execute等），配置您的数据库凭据。凭据存储在本地，并通过自定义标头发送：

{
  "mcpServers": {
    "TiDB Cloud": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp-server-tidbcloud.workers.dev/mcp",
        "--header", "X-TiDB-API-Public-Key:${TIDB_CLOUD_PUBLIC_KEY}",
        "--header", "X-TiDB-API-Private-Key:${TIDB_CLOUD_PRIVATE_KEY}",
        "--header", "X-TiDB-DB-Host:${TIDB_CLOUD_DB_HOST}",
        "--header", "X-TiDB-DB-User:${TIDB_CLOUD_DB_USER}",
        "--header", "X-TiDB-DB-Password:${TIDB_CLOUD_DB_PASSWORD}"
      ],
      "env": {
        "TIDB_CLOUD_PUBLIC_KEY": "your-public-key",
        "TIDB_CLOUD_PRIVATE_KEY": "your-private-key",
        "TIDB_CLOUD_DB_HOST": "gateway01.us-east-1.prod.aws.tidbcloud.com",
        "TIDB_CLOUD_DB_USER": "your-username",
        "TIDB_CLOUD_DB_PASSWORD": "your-password"
      }
    }
  }
}

要获取集群的主机，请使用 tidbcloud_get_cluster 工具-它将显示连接端点。您的用户名格式通常为 {userPrefix}.root 哪里 userPrefix 如集群详细信息所示。

可用工具

区域工具

tidbcloud_list_regions

列出TiDB Cloud无服务器集群的所有可用区域。

参数： 无

群集管理

tidbcloud_list_clusters

列出您组织中的所有TiDB Cloud无服务器集群。

参数：

• pageSize （可选）：每页的簇数（1-100，默认10）
• pageToken （可选）：用于获取下一页的令牌

tidbcloud_get_cluster

获取特定群集的详细信息，包括连接端点（主机和端口）。

参数：

• cluster （必填）：集群名称或ID

tidbcloud_create_cluster

创建新的TiDB Cloud无服务器集群。这是一个异步操作-集群最初将处于CREATING状态。

参数：

• displayName （必需）：群集的显示名称（最多64个字符）
• region （必填）：云区域名称（使用 tidbcloud_list_regions 获取有效值）
• rootPassword （可选）：根密码。如果未提供，则自动生成
• spendingLimitMonthly （可选）：每月支出限额（美元）
• labels （可选）：集群的键值标签

tidbcloud_update_cluster

更新现有群集的配置。

参数：

• cluster （必需）：要更新的群集名称或ID
• displayName （可选）：新显示名称
• spendingLimitMonthly （可选）：每月支出限额（美元）
• labels （可选）：键值标签

tidbcloud_delete_cluster

删除群集。 警告：这是不可逆转的！

参数：

• cluster （必填）：要删除的群集名称或ID

分行管理

tidbcloud_list_branches

列出集群的所有分支。

参数：

• cluster （必填）：集群名称或ID
• pageSize （可选）：每页分支数量（1-100）
• pageToken （可选）：分页标记

tidbcloud_get_branch

获取特定分支的详细信息，包括连接端点。用于检查分支是否已完成创建。

参数：

• cluster （必填）：集群名称或ID
• branch （必填）：分行名称或ID

tidbcloud_create_branch

为TiDB Cloud Starter或Essential集群创建新分支。这是一个异步操作。

参数：

• cluster （必填）：集群名称或ID
• displayName （必填）：新分支的显示名称（最多64个字符）
• parentId （可选）：父分支ID（默认为主集群）
• parentTimestamp （可选）：RFC3339时间点分支的时间戳

tidbcloud_delete_branch

删除分支。 警告：这是不可逆转的！

参数：

• cluster （必填）：集群名称或ID
• branch （必填）：要删除的分支机构名称或ID

数据库操作

数据库工具需要连接凭据。通过环境变量设置它们或将其作为参数传递。

show_databases

列出TiDB Cloud集群中的所有数据库。

参数：

• host （可选）：数据库主机覆盖
• username （可选）：用户名覆盖
• password （可选）：密码覆盖

show_tables

列出指定数据库中的所有表。

参数：

• database （必填）：用于列出表的数据库
• host （可选）：数据库主机覆盖
• username （可选）：用户名覆盖
• password （可选）：密码覆盖

db_query

执行只读SQL查询。只允许使用SELECT、SHOW、DESCRIBE和EXPLAIN语句。

参数：

• sql （必需）：要执行的只读SQL查询
• database （可选）：用于查询的数据库
• host （可选）：数据库主机覆盖
• username （可选）：用户名覆盖
• password （可选）：密码覆盖

db_execute

执行修改数据或架构的SQL语句（INSERT、UPDATE、DELETE、CREATE、ALTER、DROP）。 警告：这可能会修改或删除数据。

参数：

• sql （必填）：要执行的SQL语句或语句数组
• database （可选）：要使用的数据库
• host （可选）：数据库主机覆盖
• username （可选）：用户名覆盖
• password （可选）：密码覆盖

db_create_user

创建新的数据库用户。

参数：

• username （必填）：新用户的用户名
• password （必填）：新用户的密码
• userHost （可选）：主机限制（默认值：任何主机的“%”）
• host （可选）：管理数据库主机覆盖
• adminUsername （可选）：管理员用户名覆盖
• adminPassword （可选）：管理员密码覆盖

db_remove_user

删除数据库用户。 警告：这是不可逆转的！

参数：

• username （必填）：要删除的用户的用户名
• userHost （可选）：主机规格（默认值：“%”）
• host （可选）：管理数据库主机覆盖
• adminUsername （可选）：管理员用户名覆盖
• adminPassword （可选）：管理员密码覆盖

异步操作

一些操作（集群创建、分支创建、删除）是异步的。工具将立即返回当前状态，您可以使用相应的 get 用于检查操作何时完成的工具：

• 之后 tidbcloud_create_cluster：使用 tidbcloud_get_cluster 检查状态从何时更改 CREATING 到 ACTIVE
• 之后 tidbcloud_create_branch：使用 tidbcloud_get_branch 检查状态从何时更改 CREATING 到 ACTIVE

发展

# Run in development mode with auto-reload
pnpm dev

# Build the project
pnpm build

# Clean build artifacts
pnpm clean

# Test with MCP Inspector (stdio server)
TIDB_CLOUD_PUBLIC_KEY='your-key' TIDB_CLOUD_PRIVATE_KEY='your-key' \
  npx @modelcontextprotocol/inspector node packages/server/dist/index.js

使用MCP检查器测试远程服务器

要使用API密钥身份验证在本地测试远程HTTP服务器，请执行以下操作：

1. 启动远程服务器：

pnpm dev:remote

1. 在单独的终端中，通过以下方式连接MCP检查器 mcp-remote 使用API密钥头：

npx @modelcontextprotocol/inspector \
  npx mcp-remote http://localhost:3000/mcp \
  --header "X-TiDB-API-Public-Key:YOUR_PUBLIC_KEY" \
  --header "X-TiDB-API-Private-Key:YOUR_PRIVATE_KEY"

项目结构

mcp-server-tidbcloud/
├── packages/
│   ├── server/                    # Core MCP Server (stdio transport)
│   │   ├── src/
│   │   │   ├── index.ts           # Entry point
│   │   │   ├── server.ts          # MCP server setup
│   │   │   ├── config.ts          # Configuration
│   │   │   ├── api/
│   │   │   │   ├── client.ts      # TiDB Cloud API client
│   │   │   │   └── types.ts       # Type definitions
│   │   │   ├── db/
│   │   │   │   ├── client.ts      # Database client
│   │   │   │   └── types.ts       # Database types
│   │   │   └── tools/
│   │   │       ├── index.ts       # Tool exports
│   │   │       ├── cluster.ts     # Cluster management tools
│   │   │       ├── branch.ts      # Branch management tools
│   │   │       ├── database.ts    # Database SQL tools
│   │   │       └── region.ts      # Region discovery tools
│   │   ├── package.json
│   │   └── tsconfig.json
│   │
│   └── remote/                    # Remote MCP Server (HTTP transport)
│       ├── src/
│       │   ├── app.ts             # Hono web app
│       │   ├── config.ts          # Configuration
│       │   ├── dev.ts             # Local dev server
│       │   ├── landing.ts         # Landing page
│       │   ├── skill.ts           # Skill documentation
│       │   ├── worker.ts          # Cloudflare Workers entry point
│       │   └── middleware/        # Security middleware
│       ├── package.json
│       └── wrangler.toml          # Cloudflare Workers configuration
│
├── package.json                   # Root workspace config
├── pnpm-workspace.yaml
└── tsconfig.base.json

TiDB云限制

集群限制

• 无服务器集群在特定地区可用（使用 tidbcloud_list_regions 查看可用区域）
• 可以配置支出限额以控制成本

分支限制

• 每个组织最多5个分支机构（默认配额）
• 无法对大于100 GiB的群集进行分支
• 分支是在与父集群相同的区域中创建的
• 免费入门群集：时间点限制为最后24小时
• 付费集群：时间点限制为过去14天

安全

安全注意事项

此MCP服务器具有强大的数据库管理功能。请查看以下安全指南：

• 始终审查行动：在执行之前审查和授权LLM要求的行动
• 开发利用：此服务器用于本地开发和IDE集成
• API密钥安全：永远不要在客户端代码或公共存储库中公开API密钥
• 访问控制：确保只有授权用户才能访问您的MCP服务器URL
• 审核访问权限：监控使用情况并定期审核谁可以访问您的API密钥

环境变量安全

• 使用环境变量或秘密管理工具安全地存储API密钥
• 永不承诺 .env 包含真实凭据的文件
• 定期旋转API密钥

只读模式

为了更安全的操作 db_query 该工具只允许只读SQL语句（SELECT、SHOW、DESCRIBE、EXPLAIN）。对于数据修改，请使用 db_execute 小心。

有关更多信息，请参阅 MCP安全最佳实践.

许可证

麻省理工学院