如何在内网配置 TiDB 数据库 Agent

昨天的文章已经实现了通过 FastAPI + OpenAI + pyTiDB 的方式搭建 Agent 智能体，也在文章结尾演示了在聊天框中操作数据库。但是因为此种方式要手写一个 FastAPI http 接口，加上 Centos 7.9 的系统，GCC 和 Python 版本都较低，操作相对复杂。

因此，这次我们使用 RockyLinux 的系统，再配置一次 TiDB 数据库的 Agent，这里我们就演示通过 MCP SSE 的方式，先介绍和对比一下这两种方式。

1. MCP VS FastAPI

在将 TiDB 的能力接入 Dify 时，主要有两种可选方案：一种是：原生 MCP (SSE) 模式（达梦的此种方式弄了很久没搞成功）; 另一种是：FastAPI 自定义桥接 + OpenAPI 的 Custom Tool 模式。 以下是二者对比与适用场景分析：

📊 核心多维度对比

💡 适用场景分析与选型建议

1. 优先选择 方式一：原生 MCP (SSE) 模式

• 内部 PoC / 快速原型验证：希望以最快速度搭建演示系统，验证 LLM + TiDB 的 RAG 或 Data Agent 能力。
• 数据分析/报表 Agent：主要用于内部数据查询与分析，允许 AI 灵活用 SQL 进行多维度探索。
• 低代码/无代码团队：缺乏足够的后端开发资源，希望直接复用官方生态组件。

2. 优先选择 方式二：FastAPI + OpenAPI 模式

• 生产环境上线：对数据安全、SQL 注入风险要求极高的线上业务。
• 复杂业务流：查询数据前需要鉴权/过滤，或者查库后需要拼装第三方 API 数据（如 API 聚合）。
• 面向终端用户的应用：不希望大模型直接接触数据库底层结构，仅暴露出特定的业务 API 。

总结下来就是：想省事、想快点用上就用 MCP 标准的模式；想更安全、自己完全掌控就用 FastAPI + OpenAPI 模式。

Dify、FastAPI、MCP、Ollama 等这些概念我们之前文章已经介绍了，此次部署环境如下，下面我们直接进行配置环节。

2. 安装 Dify

2.1 基础环境准备

# 1. 配置 Rocky Linux 阿里云源
sudo tee /etc/yum.repos.d/aliyun-rocky.repo << 'EOF'
[baseos]
name=Rocky Linux $releasever - BaseOS - Aliyun
baseurl=https://mirrors.aliyun.com/rockylinux/$releasever/BaseOS/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-rockyofficial

[appstream]
name=Rocky Linux $releasever - AppStream - Aliyun
baseurl=https://mirrors.aliyun.com/rockylinux/$releasever/AppStream/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-rockyofficial

[extras]
name=Rocky Linux $releasever - Extras - Aliyun
baseurl=https://mirrors.aliyun.com/rockylinux/$releasever/extras/$basearch/os/
gpgcheck=1
enabled=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-rockyofficial
EOF


# 2. 清理旧的 docker
sudo dnf remove -y podman runc docker docker-client docker-common docker-engine 
 
# 3. 配置 docker 的阿里云源
sudo dnf config-manager --add-repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

# 4. 清缓存+建缓存
sudo dnf clean all && sudo dnf makecache

# 5. 终端配置代理（可选，为了方便 git 克隆）
cat >>/etc/profile << 'EOF'
export http_proxy=http://192.168.182.1:10811
export https_proxy=http://192.168.182.1:10811
export no_proxy=localhost,127.0.0.1,*.aliyun.com,mirrors.aliyun.com
EOF

# 6. 使生效
source /etc/profile

# 7. 验证
curl -I https://google.com

2.2 安装 docker

# 1. 安装 docker 
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 2. 配置 docker 里面的代理
sudo mkdir -p /etc/systemd/system/docker.service.d

sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf << 'EOF'
[Service]
Environment="HTTP_PROXY=http://126.168.182.1:10811"
Environment="HTTPS_PROXY=http://192.168.182.1:10811"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,172.16.0.0/12,10.0.0.0/8,*.aliyun.com,://aliyun.com,*.aliyuncs.com,host.docker.internal"
EOF

# 3. 重新加载配置并重启 Docker
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl status docker

# 4. docker 安装验证
systemctl show docker --property=Environment

[root@localhost yum.repos.d]# docker --version
Docker version 29.7.2, build a7dcaa6

[root@localhost yum.repos.d]# docker compose version
Docker Compose version v5.5.0

2.3 安装 Dify

• Docker 和 Docker Compose 已全部就绪。
• 终端代理 已通，可以极速克隆 GitHub 源码。
• Docker 引擎代理 已通，可以无阻碍拉取 Docker Hub 上的 Dify 镜像。

# 1. 使用 git 克隆 dify
sudo dnf install -y git
git clone https://github.com/langgenius/dify.git

# 如果速度慢，就直接下载压缩包，解压到 opt 下面
wget https://github.com/langgenius/dify/archive/refs/heads/main.zip
unzip main.zip -d /opt/

# 2. 进入 Docker 编排目录
cd dify-main/docker

# 3. 复制生成环境变量文件
cp .env.example .env

# 修改此参数
SSRF_PROXY_ALLOW_PRIVATE_IPS=127.0.0.1,172.17.0.0/16,192.168.0.0/16

# 4. 一键拉起 Dify 服务集群
docker compose up -d

至此 Dify 在内网已经部署好了，下面我们开始配置 MCP 。

3. TiDB MCP 配置

# 1. 在 /opt 目录克隆 pytidb 项目
[root@localhost opt]# git clone https://github.com/pingcap/pytidb
正克隆到 'pytidb'...
remote: Enumerating objects: 2363, done.
remote: Counting objects: 100% (1005/1005), done.
remote: Compressing objects: 100% (494/494), done.
remote: Total 2363 (delta 778), reused 536 (delta 510), pack-reused 1358 (from 3)
接收对象中: 100% (2363/2363), 2.59 MiB | 953.00 KiB/s, 完成.
处理 delta 中: 100% (1367/1367), 完成.

# 2. 安装相关依赖
[root@localhost opt]# cd pytidb
[root@localhost opt]# sudo dnf install -y gcc gcc-c++ make python3-devel --nogpgcheck

# 3. uv 下载 Python 3.12（要求大于 3.11 版本） 并建立虚拟环境
[root@localhost pytidb]# uv venv --python python3.12
Using CPython 3.12.14
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate

# 4. 激活刚刚创建的虚拟环境
[root@localhost pytidb]# source .venv/bin/activate

# 5. 执行同步下载，拉取全部 TiDB MCP 组件及依赖
(pytidb) [root@localhost pytidb]# uv sync --extra mcp
Resolved 200 packages in 1ms
      Built pytidb @ file:///opt/pytidb                                                                 
Prepared 170 packages in 19m 34s
Installed 170 packages in 1.29s
 + aiohappyeyeballs==2.6.1
 + aiohttp==3.11.18
 + aiosignal==1.3.2
 + annotated-doc==0.0.5
 + annotated-types==0.7.0
...
# 如果报错，解决报错，清理环境重新再创建虚拟环境
rm -rf .venv/ 
uv cache clean

# 6. 查看 venv 里是 mcp 2.x 还是 1.x
(pytidb) [root@localhost pytidb]# .venv/bin/pip show mcp

# 7. 要求安装 mcp 1.x 版本
(pytidb) [root@localhost pytidb]# .venv/bin/pip install 'mcp<2'
...
Successfully installed httpx-sse-0.4.3 mcp-1.29.1

# 8. 测试是否安装成功
(pytidb) [root@localhost pytidb]# .venv/bin/python -c 'from mcp.server.fastmcp import FastMCP; print("OK")'
OK

# 9. 创建配置文件 .env 的文件，存放本地 TiDB 数据库集群凭证
cat > /opt/pytidb/.env << 'EOF'
TIDB_HOST=192.168.182.31
TIDB_PORT=4000
TIDB_USERNAME=root
TIDB_PASSWORD=root
TIDB_DATABASE=test
EOF

# 10. 启动前 source 一下
(pytidb) [root@localhost pytidb]# set -a && source .env && set +a

# 11. 一键启动常驻的 SSE 后台服务
(pytidb) [root@localhost pytidb]# .venv/bin/python -m pytidb.ext.mcp --transport sse --host 0.0.0.0 --port 8000

2026-08-29 07:53:40,840 - tidb_mcp_server - INFO - Starting tidb mcp server...
INFO:     Started server process [988751]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

现在 MCP SSE 模式已经在监听了。接下来需要配置 MCP 客户端，切换回 Dify 的网页后台。

4. Dify 集成 MCP 和大模型

4.1 安装MCP SSE插件

Windows 中打开谷歌浏览器， 输入 Dify 所在的虚拟机 IP 地址，邮箱注册并登录。在 marketPlace 中 找到 MCP SSE / StreamableHTTP（可以 ctrl + F 搜 sse），点击安装。

4.2 配置 MCP

点击 集成，选择工具插件，选择刚刚安装的 MCP SSE / StreamableHTTP，配置 API Key 授权。输入如下代码。

{
  "tidb": {
    "transport": "sse",
    "url": "http://172.17.0.1:8000/sse",
    "headers": {},
    "timeout": 60,
    "sse_read_timeout": 300
  }
}

保存后，提示操作成功。

4.3 配置大模型

在 marketPlace 中 找到 大模型厂商，Deepseek、Gemini、OpenAI 都行，这些都是在线大模型，如果本地使用 Ollama 启动了大模型，可以选择 Ollama，如何安装和集成到 Dify，请看上篇博客，这里就直接配置和使用 Deep 在线大模型。

4.4 打通数据链

第一步：创建一个 Agent（智能体）应用

1. 登录 Dify 后台，点击左边导航栏的 「Agents」。
2. 点击左侧或右上角的 「创建空白应用]，名称可以填 TiDBAgent。
3. 点击 「创建 (Create)」 进入 Agent 编排画布。

第二步：为 Agent 配置“大脑”与“提示词”

进入编排页面后，在中间的配置面板中进行以下两步操作：

1. 选择大模型 (LLM)：
   • 在左上角的下拉菜单中，选择你刚刚在第一步配好的大模型（如你配置好的 Gemini、DeepSeek 或 OpenAI ）。
2. 填写系统提示词 (Instructions)：
   • 在左侧的提示词文本框中，粘贴以下专门针对 TiDB MCP 优化的引导词：

# 角色
你是一个高级分布式数据库 TiDB 的数据分析专家。你能够完美理解用户的中文业务诉求，并自动通过调用 TiDB 工具箱来获取真实数据。

# 核心工作流
1. 当用户让你查询、分析数据时，如果不知道表结构，请【必须】首先调用 `show_tables`（或相关获取结构的工具）查看有哪些表。
2. 理解表结构后，根据用户的意图编写准确、高效且安全的 SQL 语句。
3. 调用 `db_query` 工具执行你编写的 SQL。
4. 拿到数据库返回的 JSON 数据后，将数据用人性化的中文大白话（或者 Markdown 表格/图表）整理并回答给用户。

# 注意事项
- 只能执行只读查询，严禁执行高危的删除或清空操作。
- 如果遇到 SQL 执行报错，请根据错误信息自我纠正 SQL 并重新尝试，直到查出结果。

第三步：为 Agent 注入 TiDB MCP 超能力

这一步是把 MCP 工具挂载到大模型身上：

1. 在配置面板中找到 「工具 (Tools)」 模块，点击右侧的 「+ 添加 (+ Add)」 按钮。
2. 在弹出的工具列表中，找到刚刚添加的 MCP SSE。

5. Agent 测试

现在已经打通了，我们与 Agent 进行对话。

5.1 场景1：询问数据库集群信息

5.2 场景2：集群有多少个 raft group

5.3 场景3：test_db 下面有几张表，数据量分别是多少

5.4 场景4：能否为tab_tidb 插入几行测试数据

至此，用 AI 来操作内网的 TiDB 数据库已经成功了，这里由于我的 Dify 所在的 Rocky Linux 可以连公网，我偷了个懒使用了 DeepSeek 在线大模型。如果内网部署了大模型（如通过 Ollama），就直接切换模型即可。Dify 相比 cursor，Dify 支持团队协同和多端共享，也就是办公室同事都可以使用。如果对概念定位还有点模糊可以翻一下之前的文章，今天的实战就到这里。

如果本文对你有所帮助，欢迎点赞、推荐和转发，也欢迎关注后续文章，一起探索 AI 如何赋能数据库运维。