数据库 MCP 服务器

多数据库统一查询的 MCP 服务器，供 Claude Code、Cursor 等 AI Agent 通过标准 MCP 工具查询各数据库的数据和元数据。

开源协议

本项目遵守你爱怎么用就怎么用不关我事但是AI不听话发狂自己把库删了别找我麻烦就行协议。

最佳实践：搭配 Skills 使用

建议配合 Skills 使用本 MCP，可实现：

• 配置感知：根据项目实际使用的数据库类型和连接信息，自动选择合适的操作策略
• SQL 持久化：要求 Agent 将执行的 SQL 迁移文件落盘保存，便于审计和溯源
• 安全规范：通过 Skills 约束 Agent 行为，防止误操作

详见 skills-template/db-migration-skill.md 模板。

功能概览

• 统一接口：一套 MCP Tools 覆盖 PostgreSQL、MySQL、ClickHouse、Oracle、SQL Server、Trino、人大金仓、Redis、TDengine 等
• 集中配置：连接信息存储在 PostgreSQL 或 SQLite 配置库，团队/个人均可共享
• 可视化管理：Admin Web UI 管理连接和数据源类型
• 安全默认：查询默认只读，自动 LIMIT，写操作需显式开启
• 查询审计：每次查询自动写入 query_log 表

支持的数据库

快速开始

1. 环境准备

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。

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：

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

cp .env.example .env

主要配置项：

4. 构建 Admin 前端（首次或前端更新后）

cd admin/frontend
npm install
npm run build    # 产出 admin/dist/
cd ../..

5. 添加数据库连接

启动 Admin 管理界面：

python admin/app.py
# 访问 http://localhost:9998

6. 启动 MCP 服务

本地开发（stdio，由客户端自动拉起）：

python server.py

团队共享（streamable-http，部署在服务器）：

python server.py --http
# 自定义端口：python server.py --http --port 9500
# 兼容别名：python server.py --sse（等价于 --http，会打印弃用提示）

验证服务（应返回 HTTP 200 与 initialize 响应）：

curl -X POST http://<server_ip>:9999/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

客户端集成

方式一：团队共享 streamable-http（推荐）

服务部署在服务器后，团队成员只需配置 URL，无需本地安装依赖。

在客户端的 MCP 配置中添加：

{
  "mcpServers": {
    "db-mcp": {
      "url": "http://<server_ip>:9999/mcp"
    }
  }
}

各客户端配置位置：

DB_MCP_PUBLIC_URL 应设为团队成员实际可访问的地址，启动 --http 模式时会在控制台打印。

方式二：本地 stdio

每台机器独立运行，适合个人开发或无共享服务器场景。

Claude Code / Cursor：

{
  "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 表格。

连接管理

Schema 探索

数据查询

推荐 Agent 工作流：

list_connections → test_connection → list_schemas → list_tables
→ describe_table → sample_table / query

安全与约束

生产部署（systemd）

deploy/ 提供两种 systemd 部署模式，二选一，不可同时启用（会抢 9999 端口），详见 deploy/README.md。以 Linux 服务器 172.16.60.230 为例，前置：部署代码、配置 .env、执行 init.sql、构建 Admin 前端。

模式一：单体模式（推荐）

由 scripts/start_all.py 统一拉起 MCP 与 Admin：启动一个两个都起、停一个两个都停。

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，故障隔离（streamable-http 无状态，Admin 重启不影响 MCP 请求），靠 Requires+PartOf 联动。

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

防火墙与验证

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 -X POST http://172.16.60.230:9999/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

扩展新数据库类型

1. 在 adapters/ 下新建适配器，继承 BaseAdapter
2. 在 adapters/__init__.py 的 ADAPTER_MAP 中注册
3. 在 Admin「管理数据源类型」或 db_types 表中添加类型记录

数据库特定说明

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 官网 下载对应平台的 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. 未识别部分文件：

#  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

Redis

Redis 为 Key-Value 数据库，与 SQL 关系型数据库使用方式不同。所有 Redis 命令通过 query 工具的 sql 参数传入。

调用模式

BaseAdapter 映射

配置说明

• Admin「数据库」字段填写 db 编号（默认 0）
• Redis 无用户名，user 字段留空
• decode_responses=False 已开启，支持二进制 Key/Value 安全显示（不可解码时回退到 repr）

支持的数据类型：String / Hash / List / Set / Sorted Set / HyperLogLog / Stream / 通用 Key 操作（TTL/EXISTS/DEL 等），命令分类详见 utils/redis_commands.py。