<div align="center"> <img src="assets/logo.svg" alt="DB MCP Server Logo" width="300" />

多数据库MCP服务器

<h3>一个强大的多数据库服务器，通过实现模型上下文协议（MCP）来提供AI助手对数据库的结构化访问。</h3> <div class="toc"> <a href="#overview">概述</a> • <a href="#core-concepts">核心概念</a> • <a href="#features">特性</a> • <a href="#supported-databases">支持的数据库</a> • <a href="#deployment-options">部署选项</a> • <a href="#configuration">配置</a> • <a href="#available-tools">可用工具</a> • <a href="#examples">示例</a> • <a href="#troubleshooting">故障排除</a> • <a href="#contributing">贡献</a> </div> </div>

概述

DB MCP服务器提供了一种标准化的方式，使AI模型能够同时与多个数据库进行交互。基于FreePeak/cortex框架构建，它使AI助手能够通过统一接口执行SQL查询、管理事务、探索模式并分析不同数据库系统中的性能。

核心概念

多数据库支持

与传统的数据库连接器不同，DB MCP服务器可以同时连接并交互多个数据库：

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "localhost",
      "port": 5432,
      "name": "db2",
      "user": "user2",
      "password": "password2"
    }
  ]
}

动态工具生成

对于每个连接的数据库，服务器会自动生成专用工具：

// 对于ID为"mysql1"的数据库，生成以下工具：
query_mysql1       // 执行SQL查询
execute_mysql1     // 运行数据修改语句
transaction_mysql1 // 管理事务
schema_mysql1      // 探索数据库模式
performance_mysql1 // 分析查询性能

清晰架构

服务器遵循清晰架构原则，具有以下层次：

1. 领域层：核心业务实体和接口
2. 存储库层：数据访问实现
3. 用例层：应用业务逻辑
4. 交付层：外部接口（MCP工具）

特性

• 同时支持多数据库：同时连接多个MySQL和PostgreSQL数据库
• 数据库特定工具生成：自动创建每个连接数据库的专用工具
• 清晰架构：模块化设计，明确职责分离
• OpenAI代理SDK兼容性：完全兼容，无缝集成AI助手
• 动态数据库工具：执行查询、运行语句、管理事务、探索模式、分析性能
• 统一接口：在不同数据库类型中具有一致的交互模式
• 连接管理：简单配置多个数据库连接

支持的数据库

数据库	状态	特性
MySQL	✅ 完全支持	查询、事务、模式分析、性能洞察
PostgreSQL	✅ 完全支持 (v9.6-17)	查询、事务、模式分析、性能洞察
TimescaleDB	✅ 完全支持	超表、时间序列查询、连续聚合、压缩、保留策略

部署选项

DB MCP服务器可以通过多种方式部署，以适应不同的环境和集成需求：

Docker部署

# 拉取最新镜像
docker pull freepeak/db-mcp-server:latest

# 使用挂载的配置文件运行
docker run -p 9092:9092 \
  -v $(pwd)/config.json:/app/my-config.json \
  -e TRANSPORT_MODE=sse \
  -e CONFIG_PATH=/app/my-config.json \
  freepeak/db-mcp-server

注意：挂载到/app/my-config.json，因为容器默认有/app/config.json文件。

STDIO模式（IDE集成）

# 在STDIO模式下运行服务器
./bin/server -t stdio -c config.json

对于Cursor IDE集成，在.cursor/mcp.json中添加：

{
  "mcpServers": {
    "stdio-db-mcp-server": {
      "command": "/path/to/db-mcp-server/server",
      "args": ["-t", "stdio", "-c", "/path/to/config.json"]
    }
  }
}

SSE模式（服务端发送事件）

# 默认配置（localhost:9092）
./bin/server -t sse -c config.json

# 自定义主机和端口
./bin/server -t sse -host 0.0.0.0 -port 8080 -c config.json

客户端连接端点：http://localhost:9092/sse

源码安装

# 克隆仓库
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server

# 构建服务器
make build

# 运行服务器
./bin/server -t sse -c config.json

配置

数据库配置文件

创建一个config.json文件，包含您的数据库连接：

{
  "connections": [
    {
      "id": "mysql1",
      "type": "mysql",
      "host": "mysql1",
      "port": 3306,
      "name": "db1",
      "user": "user1",
      "password": "password1",
      "query_timeout": 60,
      "max_open_conns": 20,
      "max_idle_conns": 5,
      "conn_max_lifetime_seconds": 300,
      "conn_max_idle_time_seconds": 60
    },
    {
      "id": "postgres1",
      "type": "postgres",
      "host": "postgres1",
      "port": 5432,
      "name": "db1",
      "user": "user1",
      "password": "password1"
    }
  ]
}

命令行选项

# 基本语法
./bin/server -t <传输> -c <配置文件>

# SSE传输选项
./bin/server -t sse -host <主机名> -port <端口> -c <配置文件>

# 内联数据库配置
./bin/server -t stdio -db-config '{"connections":[...]}'

# 环境变量配置
export DB_CONFIG='{"connections":[...]}'
./bin/server -t stdio

可用工具

对于每个连接的数据库，DB MCP服务器会自动生成这些专用工具：

查询工具

工具名称	描述
query_<db_id>	执行SELECT查询，并以表格数据集形式获取结果
execute_<db_id>	运行数据操作语句（INSERT, UPDATE, DELETE）
transaction_<db_id>	开始、提交和回滚事务

模式工具

工具名称	描述
schema_<db_id>	获取关于表、列、索引和外键的信息
generate_schema_<db_id>	从数据库模式生成SQL或代码

性能工具

工具名称	描述
performance_<db_id>	分析查询性能并获取优化建议

TimescaleDB工具

对于带有TimescaleDB扩展的PostgreSQL数据库，提供了这些额外的专用工具：

工具名称	描述
timescaledb_<db_id>	执行通用的TimescaleDB操作
create_hypertable_<db_id>	将标准表转换为TimescaleDB超表
list_hypertables_<db_id>	列出数据库中的所有超表
time_series_query_<db_id>	执行优化的时间序列查询
time_series_analyze_<db_id>	分析时间序列数据模式
continuous_aggregate_<db_id>	创建自动更新的物化视图
refresh_continuous_aggregate_<db_id>	手动刷新连续聚合

有关TimescaleDB工具的详细文档，请参阅TIMESCALEDB_TOOLS.md。

示例

查询多个数据库

-- 查询第一个数据库
query_mysql1("SELECT * FROM users LIMIT 10")

-- 在同一上下文中查询第二个数据库
query_postgres1("SELECT * FROM products WHERE price > 100")

管理事务

-- 开始事务
transaction_mysql1("BEGIN")

-- 在事务内执行语句
execute_mysql1("INSERT INTO orders (customer_id, product_id) VALUES (1, 2)")
execute_mysql1("UPDATE inventory SET stock = stock - 1 WHERE product_id = 2")

-- 提交或回滚
transaction_mysql1("COMMIT")
-- 或者
transaction_mysql1("ROLLBACK")

探索数据库模式

-- 获取数据库中的所有表
schema_mysql1("tables")

-- 获取特定表的列
schema_mysql1("columns", "users")

-- 获取约束
schema_mysql1("constraints", "orders")

故障排除

常见问题

• 连接失败：验证网络连接和数据库凭据
• 权限错误：确保数据库用户具有适当的权限
• 超时问题：检查配置中的query_timeout设置

日志

启用详细日志以进行故障排除：

./bin/server -t sse -c config.json -v

贡献

我们欢迎对DB MCP服务器项目的贡献！要贡献：

1. 分叉仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'feat: 添加神奇功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开拉取请求

请参阅我们的CONTRIBUTING.md文件以获取详细指南。

许可证

此项目根据MIT许可证发布 - 详情请参阅LICENSE文件。

</div>