内容
# 数据库 MCP 服务器
多数据库统一查询的 [MCP](https://modelcontextprotocol.io/) 服务器，供 Claude Code、Cursor 等 AI Agent 通过标准 MCP 工具查询各数据库的数据和元数据。
## 开源协议
本项目遵守你爱怎么用就怎么用不关我事但是AI不听话发狂自己把库删了别找我麻烦就行协议。
### 最佳实践：搭配 Skills 使用
建议配合 Skills 使用本 MCP，可实现：
- **配置感知**：根据项目实际使用的数据库类型和连接信息，自动选择合适的操作策略
- **SQL 持久化**：要求 Agent 将执行的 SQL 迁移文件落盘保存，便于审计和溯源
- **安全规范**：通过 Skills 约束 Agent 行为，防止误操作
详见 [`skills-template/db-migration-skill.md`](skills-template/db-migration-skill.md) 模板。
## 功能概览
- **统一接口**：一套 MCP Tools 覆盖 PostgreSQL、MySQL、ClickHouse、Oracle、SQL Server、Trino、人大金仓等
- **集中配置**：连接信息存储在 PostgreSQL 或 SQLite 配置库，团队/个人均可共享
- **可视化管理**：Admin Web UI 管理连接和数据源类型
- **安全默认**：查询默认只读，自动 LIMIT，写操作需显式开启
- **查询审计**：每次查询自动写入 `query_log` 表
## 支持的数据库
| 类型 ID | 数据库 | pip 依赖 | 默认端口 | 状态 |
| ------------ | ---------------- | ------------------ | ----- | ---------------------- |
| `postgresql` | PostgreSQL | psycopg2-binary | 5432 | ✅ |
| `mysql` | MySQL | pymysql | 3306 | ✅ |
| `clickhouse` | ClickHouse | clickhouse-connect | 8123 | ✅ |
| `oracle` | Oracle 11g / 19c | oracledb | 1521 | ✅ |
| `mssql` | SQL Server | pymssql | 1433 | ✅ |
| `kingbase` | 人大金仓 | psycopg2-binary | 54321 | ✅ 复用 PG 协议 |
| `trino` | Trino | trino | 8080 | ✅ catalog 映射为 database |
| `dm` | 达梦 | — | 5236 | ⏳ 类型已注册，适配器待实现 |
## 快速开始
### 1. 环境准备
```bash
git clone https://github.com/No-name0719/db-mcp-server.git
cd db-mcp-server
conda create -n db-mcp python=3.11 -y
conda activate db-mcp
pip install -r requirements.txt
```
### 2. 初始化配置库
支持两种配置存储方式，通过 `.env` 中 `DB_MCP_CONFIG_BACKEND` 选择：
#### 方式 A：SQLite（推荐本地/单机，无需 PostgreSQL）
SQLite 将整个数据库存为一个本地文件（默认 `./data/db_mcp_server.db`），**首次启动时会自动建表并写入预置数据源类型**，无需手动执行 SQL。
```bash
cp .env.example .env
# 编辑 .env，设置：
# DB_MCP_CONFIG_BACKEND=sqlite
# DB_MCP_SQLITE_PATH=./data/db_mcp_server.db # 可选，默认值即可
```
备份/迁移配置时，直接复制该 `.db` 文件即可。
#### 方式 B：PostgreSQL（推荐团队共享）
用一台 Bootstrap PostgreSQL 存储所有连接配置。需先创建数据库并执行初始化脚`sqls/init.sql`：
```bash
createdb -h <pg_host> -p <pg_port> -U postgres mcp
psql -h <pg_host> -p <pg_port> -U postgres -d mcp -f sqls/init.sql
```
`.env` 中保持 `DB_MCP_CONFIG_BACKEND=postgres`（默认），并填写 `DB_MCP_PG_*` 连接信息。
### 3. 配置 `.env`
```bash
cp .env.example .env
```
主要配置项：
| 变量 | 说明 | 默认值 |
| ----------------------------- | --------------------------------- | ---------------------------- |
| `DB_MCP_CONFIG_BACKEND` | 配置存储后端：`postgres` / `sqlite` | `postgres` |
| `DB_MCP_SQLITE_PATH` | SQLite 数据库文件路径（backend=sqlite） | `./data/db_mcp_server.db` |
| `DB_MCP_PG_HOST` | Bootstrap PG 主机（backend=postgres） | `localhost` |
| `DB_MCP_PG_PORT` | Bootstrap PG 端口 | `9432` |
| `DB_MCP_PG_DB` | 配置库名 | `mcp` |
| `DB_MCP_PG_USER` | Bootstrap PG 用户 | `postgres` |
| `DB_MCP_PG_PASSWORD` | Bootstrap PG 密码 | — |
| `DB_MCP_PG_SCHEMA` | 配置 schema | `db_mcp_server` |
| `DB_MCP_HOST` | MCP SSE 监听地址 | `0.0.0.0` |
| `DB_MCP_PORT` | MCP SSE 监听端口 | `9999` |
| `DB_MCP_PUBLIC_URL` | 对外 SSE 地址（供客户端配置） | `http://localhost:9999/sse` |
| `DB_MCP_ADMIN_HOST` | Admin 监听地址 | `0.0.0.0` |
| `DB_MCP_ADMIN_PORT` | Admin 监听端口 | `9998` |
| `ORACLE_CLIENT_DIR` | Oracle Instant Client 路径 | `./lib/oracle_instantclient` |
| `DB_MCP_QUERY_DEFAULT_LIMIT` | 只读查询默认行数 | `100` |
| `DB_MCP_QUERY_MAX_LIMIT` | 只读查询最大行数 | `1000` |
| `DB_MCP_SAMPLE_DEFAULT_LIMIT` | 取样默认行数 | `10` |
| `DB_MCP_SAMPLE_MAX_LIMIT` | 取样最大行数 | `100` |
| `DB_MCP_CONNECT_TIMEOUT` | 连接超时（秒） | `10` |
| `DB_MCP_WRITE_CONFIRM_REQUIRED` | 写 SQL 是否需 confirm_token 确认 | `true` |
| `DB_MCP_WRITE_CONFIRM_TTL` | confirm_token 有效期（秒） | `600` |
### 4. 构建 Admin 前端（首次或前端更新后）
```bash
cd admin/frontend
npm install
npm run build # 产出 admin/dist/
cd ../..
```
### 5. 添加数据库连接
启动 Admin 管理界面：
```bash
python admin/app.py
# 访问 http://localhost:9998
```
### 6. 启动 MCP 服务
**本地开发（stdio，由客户端自动拉起）：**
```bash
python server.py
```
**团队共享（SSE，部署在服务器）：**
```bash
python server.py --sse
# 自定义端口：python server.py --sse --port 9500
```
验证 SSE 服务：
```bash
curl http://<server_ip>:9999/sse
# 或使用 scripts/test_local_mcp.py（需先启动 SSE 服务）
python scripts/test_local_mcp.py
```
---
## 客户端集成
### 方式一：团队共享 SSE（推荐）
服务部署在服务器后，团队成员只需配置 URL，无需本地安装依赖。
在客户端的 MCP 配置中添加：
```json
{
"mcpServers": {
"db-mcp": {
"url": "http://<server_ip>:9999/sse"
}
}
}
```
各客户端配置位置：
| 客户端 | 配置方式 |
|--------|----------|
| **Claude Code** | 命令行 `claude mcp add db-mcp http://<server_ip>:9999/sse --transport sse -s user`，或编辑 `~/.claude.json`（Windows: `C:\Users\<用户名>\.claude.json`） |
| **Cursor** | 项目或用户级 MCP 配置文件 |
| **Qoder** | 右上角用户设置 → Qoder设置 → MCP服务 → 右上角添加 |
> `DB_MCP_PUBLIC_URL` 应设为团队成员实际可访问的地址，启动 SSE 模式时会在控制台打印。
### 方式二：本地 stdio
每台机器独立运行，适合个人开发或无共享服务器场景。
**Claude Code / Cursor：**
```json
{
"mcpServers": {
"db-mcp": {
"command": "conda",
"args": [
"run", "-n", "db-mcp", "python",
"D:/path/to/db-mcp-server/server.py"
]
}
}
}
```
将路径替换为本机项目绝对路径。Windows 下也可直接用 Python 解释器路径替代 `conda run`。
---
## MCP Tools
所有工具返回 Markdown 字符串；查询结果渲染为 Markdown 表格。
### 连接管理
| 工具 | 说明 |
| ------------------ | ------------------ |
| `list_connections` | 列出所有可用连接及配置（含备注约束） |
| `test_connection` | 测试指定连接是否可用 |
### Schema 探索
| 工具 | 说明 |
| ---------------- | ------------------------------ |
| `list_databases` | 列出数据库 / Catalog |
| `list_schemas` | 列出 Schema（⭐ 标记默认 Schema） |
| `list_tables` | 列出表和视图，支持 `table_pattern` 模糊过滤 |
| `describe_table` | 查看列名、类型、可空、默认值、注释、主键 |
| `get_ddl` | 获取建表 DDL |
### 数据查询
| 工具 | 说明 |
| -------------- | ----------------------------------------------------------- |
| `prepare_write` | 准备写操作，生成 `confirm_token` 和 SQL 预览，**不执行**；须将 SQL 与三选项（执行/拒绝/修改）同屏让用户选择 |
| `query` | 执行 SQL；只读默认 `readonly=true`；写操作需 `readonly=false` + `confirm_token`（由 prepare_write 获取） |
| `sample_table` | 快速取样 N 行 |
| `count_table` | 统计表行数 |
**推荐 Agent 工作流**：
```
list_connections → test_connection → list_schemas → list_tables
→ describe_table → sample_table / query
```
---
## 数据库特定说明
### Oracle
- **19c**：在 Admin「数据库」字段填写 **Service Name**（如 `ORCLPDB1`），thin 模式即可
- **11g**：必须启用 thick 模式，需要安装 Oracle Instant Client
#### Oracle 11g Instant Client 配置
Oracle 11g (12以下) 不支持 python-oracledb 的 thin 模式，必须通过 thick 模式连接。
**下载 Instant Client**
从 [Oracle 官网](https://www.oracle.com/database/technologies/instant-client/downloads.html) 下载对应平台的 Basic 包，解压到项目 `lib/` 目录下：
#### 常见报错(Linux)
1. **`DPY-3010: connections to this database server version are not supported by python-oracledb in thin mode`**
Oracle 11g 不支持 thin 模式，thick 模式未成功初始化。按上述步骤安装 Instant Client 并配置 `.env`。
2. 未识别部分文件：
```bash
# DPI-1047: Cannot locate a 64-bitOracle Client library:"/home/dqyt/db-mcp-server/lib/instantclient_23_26/libclntsh.so:cannot open shared object file: No such file or directory".
# 解压后可能带版本后缀，需要链接到无后缀
cd lib/instantclient_23_26
ln -sf libclntsh.so.23.1 libclntsh.so
ln -sf libocci.so.23.1 libocci.so
# 检查依赖是否全部解析
ldd lib/instantclient_*/libclntsh.so | grep "not found"
# 若输出 libnnz.so => not found 等，说明需要配置 ldconfig：
echo "/path/to/lib/instantclient_23_26" > /etc/ld.so.conf.d/oracle-instantclient.conf
ldconfig
```
### Trino
- Admin「数据库」字段填写 **Catalog**（如 `iceberg`、`hive`）
- `list_databases()` 实际执行 `SHOW CATALOGS`
- `default_schemas` 第一个值作为默认 Schema
## 安全与约束
| 项 | 说明 |
| -------- | ----------------------------------------------------------- |
| 只读默认 | `query` 默认 `readonly=true`，仅允许 `SELECT` / `WITH`，自动追加 LIMIT |
| LIMIT 范围 | 默认 100 行，最大 1000（可通过 `.env` 调整） |
| 写操作 | 须 `prepare_write` → 用户三选一（执行/拒绝/修改）→ `query(readonly=false, confirm_token=...)` |
| 写确认原则 | 每次 prepare 独立确认；SQL 变更后上一轮同意无效；token 绑定 `connection_id + sql_hash` |
| 写确认开关 | `DB_MCP_WRITE_CONFIRM_REQUIRED=false` 可跳过确认（仅建议本地调试） |
| token 有效期 | 默认 600 秒（`DB_MCP_WRITE_CONFIRM_TTL`），过期需重新 `prepare_write` |
| 认证 | Admin Web UI 和 SSE 传输**无认证**，仅适合内网部署 |
| 敏感信息 | `.env` 含 Bootstrap PG 密码，已在 `.gitignore` 排除；连接密码存于配置库 |
| 备注字段 | 可在连接备注中写明约束（如只读），Agent 通过 `list_connections` 可见 |
---
## 生产部署（systemd）
`deploy/` 提供两种 systemd 部署模式，**二选一，不可同时启用**（会抢 9999 端口），详见 [`deploy/README.md`](deploy/README.md)。以 Linux 服务器 `172.16.60.230` 为例，前置：部署代码、配置 `.env`、执行 `init.sql`、构建 Admin 前端。
### 模式一：单体模式（推荐）
由 `scripts/start_all.py` 统一拉起 MCP 与 Admin：启动一个两个都起、停一个两个都停。
```bash
sudo cp deploy/db-mcp-all.service /etc/systemd/system/
# 编辑 service 文件中的 User、WorkingDirectory、Python 路径
sudo systemctl daemon-reload
sudo systemctl enable --now db-mcp-all
```
### 模式二：分体模式（备选）
MCP 与 Admin 各自一个 service，故障隔离（Admin 重启不打断 MCP 长连接），靠 `Requires+PartOf` 联动。
```bash
sudo cp deploy/db-mcp.service deploy/db-mcp-admin.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now db-mcp db-mcp-admin
```
### 防火墙与验证
```bash
sudo firewall-cmd --zone=public --add-port=9999/tcp --permanent
sudo firewall-cmd --zone=public --add-port=9998/tcp --permanent
sudo firewall-cmd --reload
curl http://172.16.60.230:9999/sse
```
| 端口 | 用途 |
| --- | ------------ |
| 9999 | MCP SSE 服务 |
| 9998 | Admin 管理界面 |
---
## 扩展新数据库类型
1. 在 `adapters/` 下新建适配器，继承 `BaseAdapter`
2. 在 `adapters/__init__.py` 的 `ADAPTER_MAP` 中注册
3. 在 Admin「管理数据源类型」或 `db_types` 表中添加类型记录
---
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器