1. 当 AI Agent 遇上 TiDB一个真实的数据分析场景你可能已经习惯了让大模型帮你写 SQL但写完还得自己复制到数据库客户端里跑跑完再把结果贴回对话框让它分析。这个来回切换的过程就是 AI Agent 和真实数据之间那道看不见的墙。TiDB 原生支持 MCP 协议之后这道墙被拆掉了——Agent 可以直接“看见”你的表结构、自己生成 SQL、自己执行、自己拿结果画图全程不需要你手动搬运数据。MCP 全称 Model Context Protocol你可以把它理解成 AI 世界的 USB-C 接口。以前每个工具都要为每个 AI 客户端单独写适配层现在只要工具实现了一个 MCP Server所有支持 MCP 的客户端都能即插即用。TiDB 的 AI SDK PyTiDB 已经把 MCP Server 模块内置好了你不需要从零写插件配好连接参数就能让 Agent 直接查询 TiDB 里的数据。这篇文章面向的是刚接触 AI Agent 和 MCP 的小白程序员。我会带你用 TaoToken 的统一 Key 作为模型通道把 TiDB MCP Server 接进支持 MCP 的客户端5 分钟内跑通一次“自然语言提问 → Agent 查 TiDB → 返回分析结果”的完整链路。全程只需要改两个配置文件不需要写一行 Python 代码。适合谁看手头有 TiDB 测试集群或者愿意用 TiUP Playground 起一个本地实例、想体验 Agent 直连数据库做数据分析、但不想折腾复杂插件开发的开发者。如果你之前接过 Claude Desktop 或 Cursor 的 MCP 配置这篇会更顺滑如果没接过也没关系配置骨架我会直接给出来。2. 前置准备TaoToken 统一 Key 与 TiDB 连接信息在动手改配置之前先把两样东西准备好模型通道的 Key 和 TiDB 的连接串。TaoToken 在这里的角色是统一 API 通道——你不需要为不同模型分别申请 Key一个 Key 就能调用对话模型和编码模型MCP 客户端里配置的模型请求都走这个通道。2.1 获取 TaoToken API Key打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key。建议给这个 Key 起个能认出来的名字比如tidb-mcp-demo方便后续排查问题时定位。创建完成后把 Key 复制出来格式通常是sk-开头的一串字符。注意Key 只在创建时完整显示一次关掉页面就看不到了。如果没存下来直接删掉重建一个不要试图找回。TaoToken 的 API 端点地址是https://taotoken.net/api这个地址在后续配置 MCP 客户端的模型通道时会用到。如果你用的是 Claude Code 或 Anthropic 风格的客户端接入文档里有对应的 base_url 写法照着填就行。2.2 准备 TiDB 连接信息你需要四个参数host、port、username、password外加一个 database 名。如果你用的是 TiUP Playground 本地起的测试集群启动日志里会直接打印这些信息通常 host 是127.0.0.1port 是4000用户名是root密码为空。如果你连的是远程 TiDB 集群找 DBA 要一个只读权限的账号。这里有个坑不要用 root 账号跑 MCP Server因为 Agent 生成的 SQL 你无法完全预判只读权限能避免误操作。TiDB 的权限体系和 MySQL 兼容GRANT SELECT ON demo.* TO mcp_readonly%这样授权就够了。数据库里最好有现成的表和数据。如果没有可以从 OSSInsight 的 sample-data 仓库下载一份测试数据集导入里面包含 GitHub 事件数据适合做 star 趋势、仓库活跃度这类分析。导入命令用tiup dumpling或直接mysql -h 127.0.0.1 -P 4000 -u root sample.sql都行。3. 可复制配置MCP Server 与客户端骨架这一节是核心操作部分。你需要做两件事把 PyTiDB 的 MCP Server 模块拉到本地然后在 MCP 客户端里注册这个 Server。我会给出完整的 config.toml 和 settings.json 骨架你只需要替换路径和连接参数。3.1 克隆 PyTiDB 并安装依赖PyTiDB 的 MCP Server 模块在pytidb/ext/mcp目录下直接克隆整个仓库最省事git clone https://github.com/pingcap/pytidb.git cd pytidb推荐用 uv 管理 Python 环境比 pip 快很多而且能自动处理虚拟环境uv sync --extra mcp这条命令会安装 MCP 相关的额外依赖。如果你没有 uv也可以用传统方式python -m venv .venv source .venv/bin/activate pip install -e .[mcp]安装完成后记下 pytidb 仓库的绝对路径比如/Users/yourname/code/pytidb后面配置里要用。3.2 MCP 客户端配置骨架settings.json以 Claude Desktop 为例打开 Settings → Developer → Edit Config会打开一个claude_desktop_config.json文件。在里面加入 TiDB MCP Server 的配置{ mcpServers: { tidb: { command: uv, args: [ --directory, /Users/yourname/code/pytidb, run, -m, pytidb.ext.mcp ], env: { TIDB_HOST: 127.0.0.1, TIDB_PORT: 4000, TIDB_USERNAME: root, TIDB_PASSWORD: , TIDB_DATABASE: demo } } } }把--directory后面的路径换成你实际的 pytidb 仓库路径env 里的五个变量换成你的 TiDB 连接信息。如果你用的是 Cursor 或 Cline配置文件位置不同但 JSON 结构是一样的直接复制这段mcpServers块过去就行。3.3 模型通道配置config.toml如果你用的客户端支持通过 config.toml 配置模型通道比如某些 CLI 工具或自建 Agent 框架可以这样写[model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model claude-sonnet-4-20250514 [mcp_servers.tidb] command uv args [--directory, /Users/yourname/code/pytidb, run, -m, pytidb.ext.mcp] [mcp_servers.tidb.env] TIDB_HOST 127.0.0.1 TIDB_PORT 4000 TIDB_USERNAME root TIDB_PASSWORD TIDB_DATABASE demo这里base_url指向 TaoToken 的 API 端点api_key填你刚才创建的 Key。模型名根据你实际想用的填TaoToken 支持多种模型填错模型名会在请求时报错到时候换一个就行。提示config.toml 和 settings.json 不是二选一的关系。settings.json 是 MCP 客户端的 Server 注册文件config.toml 是你自己 Agent 框架的模型配置。如果你只用 Claude Desktop改 settings.json 就够了如果你在写自己的 Agent 脚本两个都要配。4. 验证请求让 Agent 查一次 TiDB 数据配置改完后重启 MCP 客户端。以 Claude Desktop 为例完全退出再重新打开不要只关窗口。重启后在输入框旁边应该能看到一个工具图标点开能看到tidb这个 Server 下面挂载的工具列表通常包括show_tables、db_query等。4.1 第一步确认表结构可见在对话框里输入列出当前数据库中的所有表并显示每张表的字段结构。Agent 会调用show_tables工具返回类似这样的结果表名: github_events 字段: id (bigint), type (varchar), actor_id (bigint), repo_id (bigint), created_at (datetime), ...如果这一步报错说连接不上 TiDB先检查 env 里的 host 和 port 是否写对再确认 TiDB 集群是否在运行。本地 Playground 的话tiup playground进程还在吗4.2 第二步发起一次真实查询表结构确认后直接问一个数据分析问题检索 pingcap/tidb 仓库的 star 历史按年累计统计每位用户只计算首次 star。用表格展示结果。Agent 会自己生成 SQL调用db_query执行然后把结果整理成表格返回。你不需要手动写任何 SQL。实测下来第一次查询可能会花 10 到 20 秒因为 Agent 要先理解表结构再生成 SQL后续同类查询会快很多。如果你想看 Agent 到底生成了什么 SQL可以在提问时加一句“同时显示你执行的 SQL 语句”。这样你能看到它调用了哪些工具、传了什么参数对排查问题很有帮助。4.3 第三步验证模型通道如果你在 config.toml 里配了 TaoToken 的模型通道可以顺便验证一下模型请求是否走通了。在 Agent 框架里发一个简单的对话请求看返回是否正常。如果报 401说明 API Key 不对如果报 404检查 base_url 是不是写成了https://taotoken.net/api而不是其他路径。5. 本篇常见错排查配置过程中最容易卡住的地方我列在下面对照着检查能省不少时间。报错command not found: uv说明 uv 没装或者不在 PATH 里。用which uv确认一下如果没有按照 uv 官方文档装一个或者把 command 改成pythonargs 改成[-m, pytidb.ext.mcp]前提是你已经激活了装好依赖的虚拟环境。报错ModuleNotFoundError: No module named pytidb说明--directory指向的路径不对或者依赖没装好。确认路径是 pytidb 仓库的根目录里面有 pyproject.toml 那一层然后重新跑一次uv sync --extra mcp。Agent 说“无法连接到数据库”检查 env 里的 TIDB_HOST 和 TIDB_PORT。如果你在 Docker 里跑 MCP Server 而 TiDB 在宿主机上host 不能写127.0.0.1要写宿主机的实际 IP 或host.docker.internal。Agent 生成了 SQL 但执行报权限错误说明你用的 TiDB 账号没有 SELECT 权限。换一个有只读权限的账号或者让 DBA 授权。不要用 root 跑生产库这是底线。模型请求报invalid api key检查 TaoToken 的 Key 是否复制完整有没有多余空格。如果 Key 没问题确认 base_url 是不是https://taotoken.net/api不要多加/v1或其他后缀具体以接入文档为准。MCP 工具列表里看不到 tidbClaude Desktop 的配置文件改完后必须完全重启不是刷新页面。如果重启后还是没有打开 Developer 模式的控制台看日志通常会有具体的加载错误信息。6. 跑通之后把 MCP 通道用起来链路跑通之后你可以做几件让这套配置真正产生价值的事。第一把常用的分析查询固化下来比如“每周活跃仓库 Top 10”“issue 关闭时长分布”每次直接问 Agent不用再写 SQL。第二如果你在写自己的 Agent 应用可以把 TaoToken 的模型通道和 TiDB MCP Server 组合起来做一个内部的数据分析助手团队成员用自然语言就能查数。TaoToken 在这里的价值是统一通道——你不需要为每个模型单独管理 Key也不用担心模型切换时配置散落各处。API Keys 页面创建的那个 Key在模型对话、Coding Plan、Agent 框架里都能复用。如果你还没创建现在去控制台建一个把上面的 config.toml 里的api_key替换掉就能跑。接入文档里有更详细的参数说明和不同客户端的配置示例遇到本文没覆盖的客户端去那里对照着改。模型对话功能可以直接在 TaoToken 控制台里试不用写代码就能验证 Key 是否可用。长期做编码和 Agent 开发的话Coding Plan 的额度比按量计费更划算具体可以看控制台里的说明。配置这件事跑通一次之后就是复制粘贴。真正花时间的是想清楚让 Agent 查什么数据、解决什么问题。TiDB 的 MCP Server 已经把最难的那层适配做完了剩下的就是你的想象力。