MCP Server 使用指南

Chat2DB 内置 MCP（Model Context Protocol）Server，可以把 Chat2DB 中已经配置好的数据源、库、Schema 暴露给任意 MCP 客户端（Claude Desktop、Cursor、Claude Code、Cline 等）。接入之后，AI 助手就能直接"看到"您的数据库，并通过自然语言完成查表、查结构、执行 SQL 等操作。

📖 它能做什么

直接在 AI 对话中操作 Chat2DB 已连接的数据库，无需再把表结构、连接信息复制来复制去。
复用 Chat2DB 的安全体系：权限、连接鉴权、SQL 审计、分页限制全部沿用 Chat2DB 的规则。
一次配置，多端可用：桌面端、Web 端、团队版都支持，切换客户端只需替换配置。

🧰 内置工具一览

当前 Chat2DB MCP Server 向 AI 客户端暴露以下 5 个工具，均通过 MCP 请求头识别目标数据源：

工具名	作用	关键参数
`list_all_databases`	列出当前数据源中所有数据库	-
`list_all_schemas`	列出某个数据库下的 Schema	`targetDatabaseName`（可选）
`list_all_tables`	列出当前库/Schema 下所有表	-
`get_tables_schema`	查询指定表的 DDL / 结构	`tableNames`（必填，数组）
`execute_sql`	执行任意 SQL，默认分页 200 条，最大 500 条	`sql`（必填）、`pageSize`（可选）

所有工具都会复用 Chat2DB 的连接池与权限校验，AI 在 MCP 中能做什么，完全取决于数据源本身的账号权限。

🚀 快速开始

步骤 1：在 Chat2DB 中开启 MCP Server

打开 Chat2DB 客户端，进入 设置 → MCP。
打开 启用 MCP Server 开关。
点击 重启客户端 让配置生效（MCP Server 默认不启动，必须重启一次）。
在同一页面复制 MCP Token。Token 只在本机可见，妥善保管；如果泄露可点击 重置 Token 刷新。

步骤 2：生成客户端配置

在需要接入的数据源列表或库详情页，点击 复制 MCP 配置，Chat2DB 会根据当前上下文自动生成带有 dataSourceId、databaseName、schemaName 的 JSON 配置。也可以手动参考下文模板填写。

生成的配置形如：

{
  "mcpServers": {
    "chat2db": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:10824/mcp",
      "headers": {
        "X-Chat2DB-MCP-Token": "你的 MCP Token",
        "X-Chat2DB-DataSource-Id": "76043",
        "X-Chat2DB-Database-Name": "movie"
      }
    }
  }
}

步骤 3：在 MCP 客户端接入

将生成的 JSON 填入各客户端的 MCP 配置即可。以下是常见客户端的接入方式。

🧩 客户端接入示例

Claude Desktop

编辑 claude_desktop_config.json（macOS 路径：~/Library/Application Support/Claude/claude_desktop_config.json），把 mcpServers 对象合并进去：

{
  "mcpServers": {
    "chat2db": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:10824/mcp",
      "headers": {
        "X-Chat2DB-MCP-Token": "你的 MCP Token",
        "X-Chat2DB-DataSource-Id": "76043"
      }
    }
  }
}

重启 Claude Desktop，在对话框的工具面板中看到 chat2db 即为成功。

Cursor

在 Settings → MCP → Add new MCP server 中，粘贴同样的 chat2db 配置即可。Cursor 会自动识别 streamable-http 类型。

Claude Code / Cline

在对应的 mcp.json 中加入上述片段，启动时即可使用 list_all_tables、execute_sql 等工具。

🔐 鉴权与请求头

Header	说明	是否必填
`X-Chat2DB-MCP-Token`	桌面 GUI 模式下的访问令牌，在 MCP 设置页获取	桌面 GUI 必填
`X-Chat2DB-DataSource-Id`	要访问的数据源 ID	✅ 必填
`X-Chat2DB-Database-Name`	目标数据库名	选填
`X-Chat2DB-Schema-Name`	目标 Schema	选填

桌面版：使用 MCP Token 鉴权，Chat2DB 仅监听 127.0.0.1，默认只接受本机请求。
Web / 团队版：沿用登录态 Cookie 或 Authorization Header，接入前请先登录对应账号。
多数据源场景：为不同库生成多个 MCP 条目（chat2db-movie、chat2db-orders 等），在同一客户端中可并存。

⚙️ 高级配置

切换端口：Chat2DB 启动端口修改后，配置中的 url 需同步更新。
HTTPS：开启 server.ssl.enabled=true 后，URL 自动变为 https://。
Server 端部署：可通过 spring.ai.mcp.server.enabled=true 在 Web/团队版 server 上开启 MCP 能力，同时建议放在内网或反向代理后使用。

❓ 常见问题

Q：AI 调用工具返回 "Missing MCP header"？
A：说明请求没有带 X-Chat2DB-DataSource-Id，请重新复制 Chat2DB 生成的配置，或手动补齐数据源 ID。

Q：Token 泄露怎么办？
A：在 设置 → MCP 点击 重置 Token，老 Token 立即失效，所有已接入的客户端需更新配置。

Q：为什么 MCP 客户端连不上？
A：请依次检查：

是否已开启 MCP 开关并重启了 Chat2DB；
端口是否与客户端配置一致；
桌面端仅监听 127.0.0.1，不要尝试从其他机器直连；
execute_sql 默认最多返回 500 条，请在提示词中让 AI 自行分页。

Q：可以限制 AI 只读吗？
A：MCP 本身不做 SQL 级别拦截，请在数据库层为 MCP 账号分配只读权限；Chat2DB 的连接仍会完整记录 SQL 审计。

AI 自然语言生成 SQL 团队协作