05_TiDB MCP Server 实战：将数据库能力接入 AI 工具生态
标签：TiDBMCPClaude CodeCursorAI编程数据库工具Model Context Protocol
关键词：TiDB MCP Server、Model Context Protocol、Claude Code集成、Cursor集成、pytidb MCP、AI数据库工具、自然语言查询、tidb-mcp-server、MCP配置
一、从"对话编程"到"对话数据库"
2024年以来，Claude Code、Cursor、GitHub Copilot 这类 AI 编程工具改变了很多开发者的工作方式——写代码可以用自然语言描述意图了。但数据库操作这一块，始终有一道墙：你得切换到数据库客户端，手写 SQL，看结果，再回来改代码。
TiDB MCP Server 的出现打破了这道墙。通过 Model Context Protocol（MCP），AI 助手可以直接"看到"数据库里有什么，用自然语言就能完成查询、建表、分析数据——全程不用切换工具，不用手写 SQL。
本文从 MCP 协议原理出发，完整讲解 TiDB MCP Server 的配置、使用和最佳实践。
二、Model Context Protocol：AI 工具集成的通用语言
2.1 MCP 要解决什么问题
在 MCP 出现之前，每个 AI 工具想要集成外部数据源，都要自己实现一套接口——OpenAI 的 Function Calling、Anthropic 的 Tool Use、各种私有 Plugin 协议。开发者苦不堪言：换一个 AI 工具，就要重写一套集成代码。
MCP（Model Context Protocol）是 Anthropic 于 2024 年底发布的开放标准，设计目标是：让 AI 工具和外部系统之间有一套统一的通信协议，类似于数据库连接的 JDBC/ODBC。
没有 MCP 的世界： Claude --> 自定义API --> 数据库 Cursor --> 不同API --> 数据库 Copilot --> 又一套 --> 数据库 有 MCP 的世界： Claude --| Cursor --|-- MCP Protocol --> MCP Server --> 数据库 Copilot-|2.2 MCP 的工作原理
MCP 采用 Client-Server 架构：
AI 工具（MCP Client） MCP Server | | | 工具发现请求 | |------------------------------>| | | | 返回：工具列表 | |<------------------------------| | | | 调用工具：查询数据库 | |------------------------------>| | | | 执行 SQL | | +----------v----------+ | | TiDB 数据库 | | +----------+----------+ | | | 返回：查询结果 | |<------------------------------| | |MCP Server 通过 stdio 或 SSE 与 AI 工具通信，暴露一组"工具"（Tools）供 AI 调用。TiDB MCP Server 提供的工具包括：数据库元数据发现、SQL 执行、Schema 管理等。
三、TiDB MCP Server 安装配置
3.1 前置条件
# 安装 uv（Python 包管理器，uvx 命令来自 uv）pipinstalluv# 或者用 Homebrew（macOS）brewinstalluv# 验证安装uvx--version3.2 Claude Code 集成配置
方法一：命令行配置（推荐，快速上手）
# 在终端中配置 TiDB MCP Serverclaude mcpaddTiDB uvx\--from"pytidb[mcp]"tidb-mcp-server\-eTIDB_HOST="gateway01.eu-central-1.prod.aws.tidbcloud.com"\-eTIDB_PORT="4000"\-eTIDB_USERNAME="your_username"\-eTIDB_PASSWORD="your_password"\-eTIDB_DATABASE="your_database"# 验证配置是否成功claude mcp list方法二：.mcp.json 配置文件（团队共享推荐）
在项目根目录创建.mcp.json（添加到.gitignore，避免密码泄露）：
{"mcpServers":{"TiDB":{"type":"stdio","command":"uvx","args":["--from","pytidb[mcp]","tidb-mcp-server"],"env":{"TIDB_HOST":"gateway01.eu-central-1.prod.aws.tidbcloud.com","TIDB_PORT":"4000","TIDB_USERNAME":"your_username.root","TIDB_PASSWORD":"your_password","TIDB_DATABASE":"your_database","TIDB_SSL_CA":"/path/to/ca.pem"}}}}TiDB Cloud SSL 证书获取：
# TiDB Cloud Serverless 需要 SSL 连接# 在 TiDB Cloud Console -> 集群详情 -> 连接信息 -> 下载 CA 证书# 证书默认路径：~/.tidb/ca.pem3.3 Cursor 集成配置
在 Cursor 的 MCP 配置界面（Settings -> MCP），添加配置：
{"mcpServers":{"tidb":{"command":"uvx","args":["--from","pytidb[mcp]","tidb-mcp-server"],"env":{"TIDB_HOST":"your_tidb_host","TIDB_PORT":"4000","TIDB_USERNAME":"your_user","TIDB_PASSWORD":"your_password","TIDB_DATABASE":"your_db"}}}}3.4 本地 TiDB Self-Managed 配置
{"mcpServers":{"TiDB-local":{"type":"stdio","command":"uvx","args":["--from","pytidb[mcp]","tidb-mcp-server"],"env":{"TIDB_HOST":"127.0.0.1","TIDB_PORT":"4000","TIDB_USERNAME":"root","TIDB_PASSWORD":"","TIDB_DATABASE":"test"}}}}四、TiDB MCP Server 能力详解
4.1 工具列表
TiDB MCP Server 注册了以下工具，AI 可以按需调用：
| 工具名 | 功能描述 |
|---|---|
list_databases | 列出所有数据库 |
list_tables | 列出指定数据库的所有表 |
describe_table | 查看表结构（字段、类型、注释、索引） |
execute_sql | 执行任意 SQL 语句 |
create_table | 根据描述生成并执行建表语句 |
show_create_table | 查看完整的 CREATE TABLE 语句 |
4.2 元数据发现能力
这是 MCP Server 在开发场景中最有价值的能力。当 Claude Code 连接 TiDB 后，你可以直接问：
你：数据库里有哪些表？每个表大概是做什么的？ Claude：我来查看一下数据库结构... [调用 list_tables，获取所有表名] [调用 describe_table，逐一查看表结构] 数据库中有以下表： 1. users（用户表）- 存储用户基本信息，包含 id, username, email, created_at 等字段 2. orders（订单表）- 存储订单数据，关联 users 表，包含 order_status, total_amount 等 3. order_items（订单明细表）- 存储订单商品明细，关联 orders 和 products 4. products（商品表）- 商品信息，包含 category, price, stock 等 5. doc_embeddings（向量文档表）- 知识库向量数据，embedding 列为 VECTOR(1536) 整体看起来是一个电商系统...这种上下文感知能力，让 Claude Code 可以在不切换工具的情况下，理解整个数据库架构并直接编写针对性代码。
五、实战案例：Claude Code + TiDB 智能开发
5.1 案例一：AI 辅助数据库设计
场景：新建一个用户收藏功能的表 你：我需要设计一个用户收藏商品的表，要求： 1. 支持软删除 2. 收藏时可以加备注 3. 要考虑到用户查看自己收藏列表的查询性能 Claude：[调用 list_tables 查看现有表结构] 了解到已有 users 表和 products 表后，我建议如下设计： CREATE TABLE user_favorites ( id BIGINT PRIMARY KEY AUTO_INCREMENT, user_id BIGINT NOT NULL COMMENT '用户ID', product_id BIGINT NOT NULL COMMENT '商品ID', note VARCHAR(500) COMMENT '用户备注', is_deleted TINYINT(1) NOT NULL DEFAULT 0 COMMENT '软删除标记', created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP, deleted_at DATETIME COMMENT '删除时间', -- 用户查看收藏列表的核心索引 INDEX idx_user_active (user_id, is_deleted, created_at DESC), -- 防止重复收藏（排除已删除的） UNIQUE KEY uk_user_product (user_id, product_id), FOREIGN KEY fk_user (user_id) REFERENCES users(id), FOREIGN KEY fk_product (product_id) REFERENCES products(id) ) COMMENT='用户商品收藏表' ENGINE=InnoDB; 是否要我直接执行这个建表语句？5.2 案例二：自然语言数据探索
你：帮我看一下我们数据库里向量搜索的表现如何， 比如 doc_embeddings 表有多少条数据，向量维度是多少 Claude：[调用 execute_sql] SQL: SELECT COUNT(*) AS total_rows FROM doc_embeddings; 结果：total_rows = 1,247,832 [调用 execute_sql] SQL: SELECT VEC_DIMS(embedding) AS dims FROM doc_embeddings LIMIT 1; 结果：dims = 1536 [调用 describe_table(doc_embeddings)] 发现 embedding 列类型为 VECTOR(1536)，无向量索引 数据库中有 124 万条向量数据，维度 1536（OpenAI text-embedding-3-small）。 我注意到 embedding 列**没有创建向量索引**，这对于 124 万条数据的查询性能 会有很大影响。建议执行： ALTER TABLE doc_embeddings ADD VECTOR INDEX idx_embedding_cosine ((VEC_COSINE_DISTANCE(embedding))); 这个操作在后台执行，不影响在线查询。要执行吗？这个例子展示了 MCP Server 的真正价值：AI 不只是回答问题，而是主动发现潜在问题（无向量索引），并给出具体的优化建议，甚至可以直接执行修复。
5.3 案例三：AI 生成完整应用代码
你：帮我写一个 Python 函数，查询知识库中和给定文本语义最相近的 5 篇文档， 要先按 category 过滤 Claude：[调用 describe_table(doc_embeddings) 查看表结构] 了解到字段有 id, doc_id, title, content, category, embedding 好的，基于表结构生成代码： ```python import openai import pymysql from typing import Optional, List, Dict def semantic_search( query: str, category: Optional[str] = None, top_k: int = 5, conn: pymysql.Connection = None ) -> List[Dict]: """ 语义搜索知识库 :param query: 查询文本 :param category: 文档类别过滤（可选） :param top_k: 返回前 K 个结果 :param conn: TiDB 数据库连接 """ client = openai.OpenAI() # 生成查询向量 resp = client.embeddings.create( model="text-embedding-3-small", input=query ) vec = resp.data[0].embedding vec_str = "[" + ",".join(str(v) for v in vec) + "]" # 构建查询 sql = """ SELECT id, doc_id, title, content, category, VEC_COSINE_DISTANCE(embedding, %s) AS distance FROM doc_embeddings {where_clause} ORDER BY distance ASC LIMIT %s """.format( where_clause="WHERE category = %s" if category else "" ) with conn.cursor(pymysql.cursors.DictCursor) as cursor: if category: cursor.execute(sql, (vec_str, category, top_k)) else: cursor.execute(sql, (vec_str, top_k)) return cursor.fetchall()这个函数已经考虑了：
- 向量维度匹配（1536维，对应 text-embedding-3-small）
- 按 category 的可选过滤
- 使用余弦距离（适合文本语义）
- 参数化查询防 SQL 注入
### 5.4 案例四：SQL 性能优化建议你：这条查询执行很慢，帮我分析一下
SELECT * FROM orders WHERE DATE(created_at) = ‘2024-01-15’
Claude：[调用 execute_sql]
EXPLAIN SELECT * FROM orders WHERE DATE(created_at) = ‘2024-01-15’;
– 发现：type=ALL，表示全表扫描，没有用到索引
[调用 describe_table(orders)]
– 发现 created_at 字段没有索引
发现问题了：
WHERE DATE(created_at) = ‘…’ 对 created_at 使用了函数，
导致索引失效（即使有索引也用不上）created_at 字段目前没有索引
优化方案：
– 方案1：添加索引并改写查询（推荐）
CREATE INDEX idx_created_at ON orders(created_at);
– 改写查询（避免对索引列使用函数）
SELECT * FROM orders
WHERE created_at >= ‘2024-01-15 00:00:00’
AND created_at < ‘2024-01-16 00:00:00’;
– 方案2：使用函数索引（TiDB 5.0+ 支持）
CREATE INDEX idx_date_created ON orders ((DATE(created_at)));
– 然后原查询可以用
要执行优化吗？
--- ## 六、安全配置最佳实践 MCP Server 拥有直接执行 SQL 的权限，生产环境需要严格的安全控制。 ### 6.1 使用只读账户 ```sql -- 创建只读 MCP 专用账户 CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'strong_password'; GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%'; -- 不授予 INSERT/UPDATE/DELETE/DROP 等写权限 FLUSH PRIVILEGES;{"env":{"TIDB_USERNAME":"mcp_readonly","TIDB_PASSWORD":"strong_password"}}6.2 敏感数据脱敏
如果数据库包含用户隐私数据，在给 AI 使用时需要在 MCP Server 层做脱敏处理，或者创建专门的视图：
-- 创建脱敏视图供 MCP 使用CREATEVIEWv_users_safeASSELECTid,CONCAT(LEFT(username,2),'***')ASusername,CONCAT(LEFT(email,3),'***@***.com')ASemail,created_atFROMusers;-- 只给 MCP 账户 v_users_safe 的访问权限GRANTSELECTONyour_db.v_users_safeTO'mcp_readonly'@'%';REVOKESELECTONyour_db.usersFROM'mcp_readonly'@'%';6.3 .mcp.json 安全管理
# .mcp.json 不能提交到 Git（包含数据库密码）echo".mcp.json">>.gitignore# 使用环境变量代替硬编码密码# .mcp.json 中引用环境变量{"mcpServers":{"TiDB":{"command":"uvx","args":["--from","pytidb[mcp]","tidb-mcp-server"],"env":{"TIDB_HOST":"${TIDB_HOST}","TIDB_PASSWORD":"${TIDB_PASSWORD}"}}}}七、常见问题排查
问题 1：uvx 命令找不到
# 错误：command not found: uvx# 解决：确认 uv 正确安装并在 PATH 中whichuvx# 如果找不到：pipinstalluvexportPATH="$HOME/.local/bin:$PATH"问题 2：SSL 连接失败
# 错误：SSL connection error# 解决：下载 TiDB Cloud CA 证书并指定路径curl-Ohttps://letsencrypt.org/certs/isrgrootx1.pem# 在 env 中指定"TIDB_SSL_CA":"/path/to/isrgrootx1.pem"问题 3：工具调用超时
MCP Server 默认超时 30 秒，大查询可能超时。建议在 SQL 中加 LIMIT 限制返回行数，或者优化慢查询后再通过 MCP 执行。
八、总结
TiDB MCP Server 让数据库能力真正融入 AI 开发工具生态，带来的不只是效率提升，更是工作方式的改变：
- MCP 协议是 AI 工具与外部系统集成的通用标准，TiDB 官方支持
- 安装配置简单：
uvx --from pytidb[mcp] tidb-mcp-server加环境变量即可 - 四大核心价值：元数据自动发现、自然语言查询、SQL 执行与调优、Schema 管理
- 安全第一：生产环境务必使用只读账户，敏感数据做脱敏视图
- 实际体验：结合 Claude Code，数据库设计、调优建议、代码生成效率提升 3 倍以上
下一篇我们进入 LangChain 和 LlamaIndex 集成，看 TiDB 如何在主流 AI 框架中扮演向量存储的角色，构建端到端 RAG 应用。
相关资源：
- TiDB MCP Server 官方文档
- Model Context Protocol 官网
- pytidb GitHub
