# 让 Claude 直接查你的数据库：用 Chat2DB 搭一个 MCP Server 实战

> 用 Docker 起一个 Chat2DB，开 MCP，把 Claude / Cursor 接上，往后查库、写 SQL、排错都能用自然语言——不用再来回切窗口。

---

数据库客户端很多，Navicat、DBeaver、DataGrip，哪个都好用。但它们有个共同点：你和数据库之间，总隔着一层自己手写 SQL 的活儿。

前阵子我把 Chat2DB 的 MCP 接口接到了 Claude Code 上，才发现这事能换个玩法——AI 直接连上你的库，自己列库、读表结构、写 SQL、跑、看结果，全在对话里完成。

这篇是一次完整实战，从零开始：用 Docker 起一个 Chat2DB，开它的 MCP Server，把配置贴进 Claude Code，最后用一句话查出一周内下单最多的十个用户。

---

## 一、Chat2DB 是什么，为什么要拿它做 MCP

Chat2DB Community 是一个开源的跨平台数据库客户端，Windows、macOS、Linux 都能跑。它能连 30 多种数据库——MySQL、PostgreSQL、Oracle、SQL Server、ClickHouse、MongoDB、Redis，还有达梦、人大金仓、OceanBase 这些国产库。

它自己也带了 AI 助手：支持 OpenAI、Claude、Gemini 三类模型，凡是兼容 OpenAI 接口的端点（Ollama、vLLM 这些）也能挂上来。接好就能用自然语言生成、解释、优化 SQL。

但真正让我眼前一亮的，是 5.3.0 之后的一个能力：**Chat2DB 把自己开成了一个 MCP Server。**

MCP（Model Context Protocol）是 Anthropic 提的一个开放协议，规定了 AI 模型怎么调用外部工具。说白了，只要一个程序按 MCP 协议把工具开出来，任何 MCP 客户端——Claude Code、Cursor、Cline——都能直接调它。

Chat2DB 一共开了 7 个工具：

| 工具 | 作用 |
| --- | --- |
| `list_all_datasources` | 列出已配置的所有数据源 |
| `list_all_databases` | 列出某个数据源下的所有库 |
| `list_all_schemas` | 列出某个库下的所有 schema |
| `list_all_tables` | 列出库里的所有表 |
| `get_tables_schema` | 读表的建表语句 / 结构 |
| `execute_sql` | 执行 SQL 并返回结果 |
| `text2sql` | 用 Chat2DB 内置 AI 把自然语言转成 SQL |

这带来的好处是：你不用把数据库连接信息交给 Claude，也不用让 AI 自己去拼 JDBC。Claude 通过 Chat2DB 这个"中间人"操作数据库，连接管理、加密、权限这些脏活全归 Chat2DB。AI 只管想和问，执行那一层是现成的数据库客户端。

这个分层挺关键，后面会展开。先把环境跑起来。

---

## 二、用 Docker 起一个 Chat2DB

### 2.1 先生成加密密钥

Chat2DB 用 AES-256-GCM 加密保存的数据源密码和 AI 模型的 API Key，每个装好的实例一把独立密钥。启动前必须先建好，不然 Web 模式会直接起不来。

```bash
git clone https://github.com/OtterMind/Chat2DB.git && cd Chat2DB
./script/security/init-community-encryption-key.sh
```

这个脚本依赖 `openssl`，会生成一个 32 字节的密钥，写成 Base64，落到 `~/.config/chat2db-community/encryption.key`。

**这把密钥一定单独备份。** 容器重建、升级，都得留着同一个文件。丢了它，已经保存的数据源密码和 API Key 就全解不开了。

### 2.2 启动容器

```bash
docker run --detach \
  --name chat2db-community \
  --restart unless-stopped \
  --publish 127.0.0.1:10825:10825 \
  --volume "$HOME/.chat2db-community-docker:/root/.chat2db-community" \
  --env CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/run/secrets/chat2db-community-encryption.key \
  --volume "$HOME/.config/chat2db-community/encryption.key:/run/secrets/chat2db-community-encryption.key:ro" \
  chat2db/chat2db:latest
```

几个参数说一下：

- `--publish 127.0.0.1:10825:10825`：只绑本机回环。Chat2DB Community 是单用户、本机优先的应用，**别把 10825 暴露到公网或不可信网络**。
- 第一个 `--volume`：应用数据持久化。
- 第二个 `--volume`：把刚才生成的密钥文件，只读挂进容器。

容器内监听的是 `0.0.0.0:10825`，靠宿主机这侧的 `127.0.0.1` 绑定来卡住访问范围。这点是故意的——默认就得安全。

启动完，浏览器打开 `http://localhost:10825`，看到 Chat2DB 界面就成了。

### 2.3 接一个数据源

在界面里新建数据源，填 host、端口、用户名、密码，连一个你有权限查的库（拿个测试库最稳）。连上以后，左边树里就能看到库和表。

这步和普通数据库客户端没区别。区别在下一步。

---

## 三、开启 MCP，生成接入配置

### 3.1 在设置里打开 MCP

Chat2DB 的 MCP Server **默认是关着的**，得进设置手动开。

在 Chat2DB 界面的设置里找到 MCP 开关，打开。源码里这个开关读的是 `settings.json` 里的 `ENABLE_MCP` 字段，默认 `false`——所以装完不能直接用，得自己开。

开了以后，后端的 `McpStarter` 会按 `spring.ai.mcp.server.enabled=true` 起一个 MCP Server，端点挂在 `http://127.0.0.1:10825/mcp`，传输方式是 `streamable-http`。

### 3.2 复制 MCP 配置

在 Chat2DB 界面里，对着数据源或表右键，菜单里有个"复制 MCP 配置"（Copy MCP Config）。点一下，剪贴板里就是一段标准 MCP 客户端配置 JSON。

它大概长这样：

```json
{
  "mcpServers": {
    "chat2db": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:10825/mcp",
      "headers": {
        "Cookie": "CHAT2DB_USER_ID=xxx; CHAT2DB_ORGANIZATION_TOKEN=yyy"
      }
    }
  }
}
```

这段配置是 Chat2DB 根据当前运行模式自动生成的。我读源码的时候发现，它对两种模式做了区分：

- **Web / Docker 模式**（也就是我们现在用的）：认证走 Cookie 和 Authorization 头，配置里带的是你当前登录会话的 Cookie。所以这段配置跟你的登录态绑着，换设备或重新登录，得重新复制一次。
- **Desktop GUI 模式**：走一个单独的 `X-Chat2DB-MCP-Token` 头，token 是第一次用时自动生成的一个 UUID，可以手动重置。

这个区分很重要——它直接决定你的 MCP 客户端能不能连上。Docker 跑的就是 Web 模式，认 Cookie。

---

## 四、接到 Claude Code

### 4.1 写入 MCP 配置

Claude Code 读的是 `~/.claude.json`（或项目级 `.mcp.json`）里的 `mcpServers`。把上一步复制的配置合并进去：

```json
{
  "mcpServers": {
    "chat2db": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:10825/mcp",
      "headers": {
        "Cookie": "CHAT2DB_USER_ID=xxx; CHAT2DB_ORGANIZATION_TOKEN=yyy"
      }
    }
  }
}
```

嫌手改 JSON 麻烦，也能用命令行一步加好：

```bash
claude mcp add --transport http chat2db http://127.0.0.1:10825/mcp \
  --header "Cookie: CHAT2DB_USER_ID=xxx; CHAT2DB_ORGANIZATION_TOKEN=yyy"
```

### 4.2 验证连接

重启 Claude Code，在新会话里输入：

```
/mcp
```

应该能看到 `chat2db` 这个 server 是 `connected`，旁边还列着它提供的 7 个工具。看到工具列表，链路就通了。

### 4.3 第一次对话

试着问一句：

> 帮我看看 chat2db 里有哪些数据源，每个数据源下有哪些库。

Claude 会先调 `list_all_datasources`，再对每个数据源调 `list_all_databases`，然后把结果整理给你。整个过程你只说了一句话。

再进一步：

> 选 orders 库，查最近 7 天下单金额最高的 10 个用户，给我看看结果。

Claude 的动作链一般是这样：`list_all_tables` 找到相关表 → `get_tables_schema` 读表结构弄清字段 → 自己写 SQL → `execute_sql` 跑 → 把结果表给你。要是它觉得得先理清表关系，还会先调 `text2sql` 让 Chat2DB 内置 AI 帮忙生成，再复核着执行。

---

## 五、接 Cursor 和其他客户端

MCP 是个协议，不是 Claude 专属的。同样的配置换个客户端也能用，区别主要在各客户端的配置文件路径和字段写法。

**Cursor**：Cursor 也支持 MCP。具体配置位置和字段格式以 Cursor 官方文档为准（`docs.cursor.com`），把上一步的 `mcpServers` JSON 按它的要求写进对应配置文件就行。

**Cline / Roo Code 这些**：各自都有 MCP 设置入口，按客户端要求填入 streamable-http 类型的 URL 和 headers。具体步骤看各客户端文档。

**统一接口**：只要客户端认 `streamable-http` 传输和自定义 headers，就能接。配置结构是通用的，差异只在各客户端的配置位置。

这就是 MCP 协议的价值——接一次，到处能用。你的数据库能力不绑死在某个客户端上。

> 注：Cursor、Cline 这些客户端的配置路径和调用方式，随版本变得挺快，本文不逐一写死，以各客户端当前的官方文档为准。

---

## 六、这套架构背后的设计

到这儿你已经能用了。下面聊聊它背后的设计，这套分层不是随手拼出来的。

### 6.1 AI 和数据库之间，多了一层"执行体"

不少 MCP 教程会教你怎么写一个"直连数据库"的 MCP Server——AI 拿到连接串，自己拼 SQL 自己跑。能跑，但有两个隐患：一是连接信息暴露在模型上下文里；二是 SQL 执行没有成熟客户端那些保护（结果分页、超时、大小写、方言差异）。

Chat2DB 的做法是把自己当执行体。AI 调 `execute_sql`，真正连库、执行、分页返回的是 Chat2DB 这套数据库客户端逻辑。`execute_sql` 对 SELECT 结果做了分页——底层默认每页最多 1000 行（`MAX_PAGE_SIZE` 常量），AI 也可以主动传一个更小的 `pageSize`，免得一把梭把百万行结果灌进上下文。

连接信息、密码、API Key 全程不进 AI 的上下文——它们被 AES-256-GCM 加密存在 Chat2DB 本地，AI 只拿到一个 `dataSourceId`。

### 6.2 插件化的方言隔离

Chat2DB 能连 30 多种库，不是靠一堆 if-else 硬撑。它后端用 Maven 多模块，每个数据库是一个独立插件（`chat2db-community-mysql`、`chat2db-community-postgresql`……），方言相关的行为锁在各自插件里，通过 SPI 接口跟核心对接。

直接的好处是：加一种新数据库，不用动核心代码；某个库的 SQL 解析出了问题，也不会污染别的库。从 MCP 的角度看，AI 调的是统一接口，底下是哪国方言的库，对它来说都是透明的。

### 6.3 本机优先的安全边界

整套设计翻来覆去强调一个词：本机。

HTTP 绑 `127.0.0.1`，密钥文件单独管，单用户模型不做多租户权限。Desktop GUI 模式更激进——开了 MCP 之后，HTTP 层只放行 `/mcp` 路径，其他请求一律返回 404，把 Web 界面在 MCP 模式下彻底锁掉。

这种"默认收紧"的做法，对一个要碰数据库密码的工具来说是该有的态度。源码里 `DesktopMcpHttpFilter` 那段直接 `SC_NOT_FOUND` 的处理，比写一堆鉴权逻辑利索多了。

---

## 七、几个实战中会踩的点

**1. Cookie 过期就连不上。** Web 模式的 MCP 配置带着登录 Cookie，会话一失效就得重新登录 Chat2DB，再复制一次。想长期跑，Desktop 模式的 token 机制更稳。

**2. 别把 10825 暴露到公网。** Community 版没有多用户权限边界，绑回环是它的安全前提。要远程用，走 SSH 隧道，别去改 `--publish` 的地址。

**3. AI 写的 SQL 先看一眼再跑。** `execute_sql` 是真执行。生产库上让 AI 动手前，最好给它一个只读账号，或者先让它把 SQL 写出来你过一眼。读结构的工具（`list_all_tables`、`get_tables_schema`）可以放心用，写操作得谨慎。

**4. 密钥丢了，数据源全失效。** `encryption.key` 一定单独备份。容器升级、换机器，第一件事就是确认这把密钥还在。

**5. MCP 默认是关的。** 装完连不上别急，先确认设置里 MCP 开关打开了，再确认配置里的 Cookie 是当前会话的。

---

## 八、收尾

这篇走完整条链路：Docker 起 Chat2DB → 生成加密密钥 → 接数据源 → 开 MCP → 复制配置 → 接 Claude Code → 自然语言查库。

核心就一句话：**Chat2DB 把一个现成的数据库客户端，包成了 AI 能直接调用的 MCP Server。** AI 管想和问，Chat2DB 管连和执行，密码、连接信息全程不出本机。

如果你日常要和数据库打交道，又已经在用 Claude Code 或 Cursor，这套组合值得花一小时搭起来。第一次看到 AI 自己列库、读表结构、写出能跑的 SQL，再把结果摆在你面前时，那种"数据库长出了嘴"的感觉，是光用数据库客户端给不了的。

用 Docker 起一个 Chat2DB，开 MCP，把 Claude / Cursor 接上，往后查库、写 SQL、排错都能用自然语言——不用再来回切窗口。

让 Claude 直接查你的数据库：用 Chat2DB 搭一个 MCP Server 实战

软件研发

数据库

使用Docker搭建Chat2DB并开启MCPServer，让Claude/Cursor直接连接数据库。通过自然语言查询数据、生成SQL、分析结果，无需切换窗口。支持30多种数据库，包括MySQL、PostgreSQL等，实现AI与数据库的安全交互。详细教程包含密钥生成、容器部署、MCP配置及Claude集成步骤，提升数据库操作效率。

代码解释

PostgreSQL

Windows

MongoDB

容器

Docker

Linux

MySQL

Redis

JSON

2026上云采购 | AI焕新·智启新局

腾讯云数据库特惠，新用户首单0.5折起


sqlserver

tchousec

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

使用Docker搭建Chat2DB并开启MCPServer，让Claude/Cursor直接连接数据库。通过自然语言查询数据、生成SQL、分析结果，无需切换窗口。支持30多种数据库，包括MySQL、PostgreSQL等，实现AI与数据库的安全交互。详细教程包含密钥生成、容器部署、MCP配置及Claude集成步骤，提升...

让 Claude 直接查你的数据库：用 Chat2DB 搭一个 MCP Server 实战-腾讯云开发者社区-腾讯云

让 Claude 直接查你的数据库：用 Chat2DB 搭一个 MCP Server 实战

让 Claude 直接查你的数据库：用 Chat2DB 搭一个 MCP Server 实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐