db-mcp-server
by NibelungT
README.md
# db-mcp-server
给 AI 用的多数据源查询服务,支持 MySQL 与 PostgreSQL,带一个网页配置中心。
解决的问题很具体:**同一个服务在不同环境(开发 / 测试 / 预发 / 生产)连着不同的库**。AI 只有一张 `execute_sql(sql)` 的手牌时,很容易查了测试库却让用户以为在看生产数据。这个项目让 AI 说"查订单服务的测试库",而不是让它猜一个连接串。
```
用户:查一下订单服务的测试库有多少张表
↓
AI 调用 query(sql="...", project="订单服务", env="test")
↓
服务端解析 → order-test · 测试 · myapp_order
↓
返回结果,并附一行来源标注
```
## 特性
| | |
|---|---|
| **按项目路由** | 项目名或别名(`订单服务` / `order` / `订单`)都能命中,一个项目在每个环境绑一个数据源 |
| **MySQL + PostgreSQL** | 差异收敛在 `db_dialect.py`,列信息、表列表、引用方式对外一致 |
| **显式指定必须命中** | 说了 `env=prod` 但没绑生产库,直接报错并列出已绑定的环境,**不会降级**到别的库返回数据 |
| **只读保护** | 标记为只读的数据源(通常是生产),`execute` 在服务端被拒绝,不依赖 AI 自觉 |
| **配置热加载** | 配置中心改完数据源,MCP 下次调用就生效,不用重启客户端 |
| **执行记录** | 每次查询落 `query_log.jsonl`,界面可分页查看:时间、来源、SQL、耗时、成功/失败、失败原因 |
| **无库模式** | MySQL 下 `database` 可留空,用 `库名.表名` 跨库查询 |
| **单文件前端** | 零构建、零框架,改样式只需编辑 `webui/index.html` |
## 界面
启动后打开 `http://127.0.0.1:8765`:
- 上半部分:**数据源**(按环境分 tab)与**项目映射**左右并列,各有常驻的新增入口
- 下半部分:**执行记录**,左侧查询流水,右侧成功/失败/平均耗时统计
只有 `127.0.0.1` 监听,没有登录鉴权,靠回环地址隔离。
## 快速开始
### 1. 安装依赖
```bash
python -m pip install -r requirements.txt
```
需要 Python 3.10+(用到了 `str | None` 类型标注)。依赖:`mcp`、`mysql-connector-python`、`psycopg[binary]`、`python-dotenv`、`fastapi`、`uvicorn`。
### 2. 启动配置中心
```bash
python webui_server.py
```
或双击 `start_webui.bat`(Windows)。端口从 8765 起,被占用就自动顺延,启动时会打印实际地址。
首次运行若 `config.json` 不存在,会从 `.env` 尝试迁移一份;没有 `.env` 就用默认配置(dev / test / staging / prod 四个环境)。
### 3. 配置数据源和项目
**新增数据源** —— 填主机、端口、账号。库名那栏点「加载库列表」可以真实连库列出所有可访问的库,不用手打。**库名留空表示不限定库**。
**新增项目** —— 项目名 + 别名,然后给每个环境挑一个数据源。绑定规则:
- 只绑 1 个环境 → 这个环境自动成为默认,不需要配 `defaultEnv`
- 绑多个环境 → 必须指定默认环境,下拉只列出已绑定的环境
- 一个都不绑 → 保存被拦截
**设默认数据源** —— 数据源行首的星标。AI 完全不指定目标时用它。
### 4. 接入 MCP 客户端
```json
{
"mcpServers": {
"db-mcp": {
"command": "/absolute/path/to/python",
"args": ["/absolute/path/to/db_mcp_server.py"],
"env": { "PYTHONIOENCODING": "utf-8" }
}
}
}
```
三个必须注意的点:
1. **`command` 写绝对路径**。如果 `python` 是另一个未装依赖的解释器(比如被其他工具托管的版本),MCP 进程会启动失败,客户端通常只显示"未连接",不告诉你原因。
2. **`args` 也写绝对路径**。客户端拉起子进程时的 cwd 不一定是项目目录。
3. **`PYTHONIOENCODING=utf-8`**。Windows 下 Python 的 stdout 默认 GBK,而 MCP 走 UTF-8;错误信息里有中文时会出现乱码或 JSON-RPC 解析失败。
不同客户端放配置的位置:
| 客户端 | 位置 |
|---|---|
| Qoder | `~/.qoder/settings.json` → `mcpServers`,或项目根 `.mcp.json` |
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
| WorkBuddy | `~/.workbuddy/mcp.json` |
新增或删除工具后**必须重启客户端**(工具列表会被缓存);只改数据源不用。
## 工具清单
| 工具 | 用途 | 关键参数 |
|---|---|---|
| `query` | 执行 SELECT,返回 JSON 结果集 | `sql`、`params`、`project` / `env` / `datasource` |
| `execute` | 执行 INSERT / UPDATE / DELETE | 同上,只读数据源上会被拒绝 |
| `list_tables` | 列出目标库的表名 | `project` / `env` / `datasource` |
| `describe_table` | 查看表结构(列名、类型、主键) | 另加 `table` |
| `get_schema` | 完整结构(所有表及其字段) | 表多时结果很大,优先用 `describe_table` |
| `search_data` | 在所有文本字段中模糊搜索 | 另加 `table`、`keyword`、`limit` |
| `list_projects` | 列出项目、别名、各环境绑定 | — |
| `list_datasources` | 列出数据源,不含密码 | — |
`query` / `execute` 的返回里会附一行来源标注:
```
[
{ "db": "myapp_order", "host": "db-test.internal" }
]
-- 来源:order-test · 测试 · myapp_order
```
这行不是装饰。没有它,AI 查了哪个库只能靠猜。
## 目标解析优先级
```
1. datasource 显式指定 → 直接取该数据源
2. project + env → project.bindings[env]
├─ env 不在环境列表里 → 报错,列出可用 key
└─ 项目未绑定该环境 → 报错,列出已绑定的环境
3. project 无 env → 绑 1 个就用它 / 绑多个用 defaultEnv
4. 都没传 → 默认数据源 → 默认项目
5. 仍解析不出 → 报错,列出可用项目与数据源
```
第 2 条是刻意设计成"报错"的。原方案里写的是"项目没绑该环境就降级到默认环境",改成报错的原因:
```
用户:查一下订单服务的生产数据
AI:query(project="订单服务", env="prod")
降级:订单服务没绑 prod → 用测试库 → 返回测试数据
用户看着屏幕上的数字,以为那是生产环境的
```
静默给错东西比直接报错危险得多。
## CLI
同一个脚本带子命令就是命令行工具,适合调试:
```bash
python db_mcp_server.py list-projects
python db_mcp_server.py list-datasources
python db_mcp_server.py query --project 订单服务 --env test --sql "SELECT 1"
python db_mcp_server.py query --sql "SHOW DATABASES" # 走默认数据源
python db_mcp_server.py describe-table --datasource order-test --table db.tbl
```
结果 JSON 走 stdout,`-- 来源:xxx` 走 stderr,方便脚本管道处理。CLI 调用同样会写执行记录。
## 配置
`config.json`(不提交,见 `.gitignore`):
```json
{
"version": 7,
"environments": [
{ "key": "test", "label": "测试", "order": 2, "readonlyHint": false },
{ "key": "prod", "label": "生产", "order": 4, "readonlyHint": true }
],
"global": {
"defaultDatasource": "ds_order_test",
"defaultProject": null,
"defaultEnv": null
},
"datasources": [
{
"id": "ds_order_test",
"alias": "order-test",
"env": "test",
"driver": "mysql",
"host": "10.0.0.1",
"port": 3306,
"user": "readonly_user",
"password": "${ORDER_TEST_PASSWORD}",
"database": "",
"schema": "",
"readonly": false
},
{
"id": "ds_report_dev",
"alias": "report-dev",
"env": "dev",
"driver": "postgres",
"host": "10.0.0.9",
"port": 5432,
"user": "report_ro",
"password": "${REPORT_PASSWORD}",
"database": "analytics",
"schema": "biz",
"readonly": true
}
],
"projects": [
{
"id": "p_order",
"name": "订单服务",
"aliases": ["order", "订单"],
"defaultEnv": "test",
"bindings": { "test": "ds_order_test" }
}
]
}
```
从零开始可以照抄 `config.example.json`。
**密码两种写法**:
- 明文 `"password": "secret"` —— 简单,适合内网自用
- 变量引用 `"password": "${ORDER_TEST_PASSWORD}"` —— 从环境变量取,配置文件可以安全备份和分享
界面上密码始终显示为 `******`,编辑时留空即保持原值。
**环境变量**:
| 变量 | 作用 |
|---|---|
| `DB_MCP_CONFIG` | 指向另一个配置文件,测试时用,避免污染真实配置 |
| `DB_MCP_LOG` | 指向另一个执行记录文件 |
## PostgreSQL 支持
`driver` 填 `postgres`(`postgresql` / `pg` 也认),端口自动用 5432。语义上和 MySQL 有一处关键差别:
**MySQL 的「库」是 database,PG 的是 schema。**
| | MySQL | PostgreSQL |
|---|---|---|
| 连接绑定 | 一个 database | 一个 database |
| `库名.表名` 的第一段 | database | **schema** |
| 跨库查询 | 支持(`a.t` 与 `b.t` 同语句) | **不支持**,只能跨 schema |
| 默认命名空间 | 所连的 database | `public`,或用 `schema` 字段指定 |
| 文本搜索 | `LIKE`(默认不区分大小写) | `ILIKE`(显式不区分大小写) |
所以给 PG 配数据源时,`database` 必填(PG 强制要求),`schema` 可选:
```json
{
"driver": "postgres",
"host": "10.0.0.9",
"port": 5432,
"database": "analytics",
"schema": "biz"
}
```
配了 `schema` 之后,`list_tables` / `get_schema` 只枚举该 schema;`describe_table` 仍可用 `其他schema.表名` 显式覆盖。
列信息做了统一:MySQL 的 `Field/Type/Null/Key` 和 PG 的 `information_schema` 都归一成 `name/type/nullable/key/default/extra`,主键统一标 `PRI`。所以 AI 在两个库之间切换时看到的字段结构长得一样。
结果里的来源标注会带上 schema,一眼能看出查的是哪个命名空间:
```
-- 来源:report-dev · 开发 · analytics/biz
```
## 目录结构
```
config_store.py 配置层:原子写、mtime 热加载、密码解析、解析器、乐观锁
db_dialect.py 方言层:MySQL / PostgreSQL 的连接、引用、元数据查询
db_mcp_server.py MCP 服务(stdio)+ CLI,8 个工具
webui_server.py FastAPI 后端,18 个路由
query_log.py 执行记录:JSONL 追加、5MB 轮转、分页、统计
migrate_env.py .env → config.json,幂等
webui/index.html 配置界面,单文件零构建
```
**两条硬约束**:
- `config_store.py` 的 `resolve()` 是 MCP 服务和 Web 界面共用的唯一解析入口。两边各写一套的话,会出现"界面显示默认是测试库、AI 实际查了生产库"这种无法排查的问题。
- 所有数据库差异只准出现在 `db_dialect.py`。业务代码里出现第二处 `if driver == ...`,就说明方言层漏了东西。
## 安全
- **只监听 `127.0.0.1`**,没有登录鉴权。不要改成 `0.0.0.0`——界面上存着数据库凭据
- **`config.json`、`.env`、`query_log.jsonl` 已加入 `.gitignore`**。执行记录里有完整 SQL,泄露的业务信息比密码更多
- **只读拦截在服务端**。AI 看不到密码,也绕不过 `readonly` 检查
- 生产库建议:`readonly: true` + 只读账号 + 密码用变量引用,三重
## 已知限制
| 限制 | 说明 |
|---|---|
| 只支持 MySQL / PostgreSQL | 接第三种库只需在 `db_dialect.py` 加一个子类,业务代码不用动 |
| PostgreSQL 不支持跨 database | 只能跨 schema;要查另一个库得单独配一个数据源 |
| PG 的 `list_tables` 按 schema 枚举 | 配了 `schema` 就只看这个 schema,不会列出全库所有 schema 的表 |
| 无登录鉴权 | 靠回环地址隔离 |
| `list_tables` / `get_schema` 在 MySQL 无库数据源上不可用 | `SHOW TABLES` 必须有当前库,会给出提示改用 `库名.表名` |
| `get_schema` 不缓存 | 表多的库较慢,优先用 `describe_table` |
| 一个项目每环境只能绑一个数据源 | 需要"一个环境查两个库"时用无库数据源 + 全限定名 |
## License
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data