多数据库 MCP 服务器
什么是 DB MCP 服务器？
DB MCP 服务器为 AI 模型提供了一种标准化的方式，使其能够同时与多个数据库交互。它基于FreePeak/cortex框架构建，使 AI 助手能够通过统一的界面执行 SQL 查询、管理事务、探索模式并分析跨不同数据库系统的性能。
核心概念
多数据库支持
与传统的数据库连接器不同，DB MCP Server 可以同时连接并与多个数据库交互：
{
"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"
}
]
}
动态工具生成
对于每个连接的数据库，服务器会自动生成一组专门的工具：
// For a database with ID "mysql1", these tools are generated:
query_mysql1 // Execute SQL queries
execute_mysql1 // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1 // Explore database schema
performance_mysql1 // Analyze query performance
清洁架构
该服务器遵循以下层的清洁架构原则：
- 领域层：核心业务实体和接口
- 存储库层：数据访问实现
- 用例层：应用程序业务逻辑
- 交付层：外部接口（MCP工具）
特征
- 同时支持多数据库：同时连接并与多个 MySQL 和 PostgreSQL 数据库交互
- 数据库特定工具生成：为每个连接的数据库自动创建专用工具
- 清洁架构：模块化设计，关注点清晰分离
- OpenAI Agents SDK 兼容性：与 OpenAI Agents SDK 完全兼容，可与 AI 助手无缝集成
- 动态数据库工具：
- 执行带参数的 SQL 查询
- 运行具有适当错误处理的数据修改语句
- 管理跨会话的数据库事务
- 探索数据库模式和关系
- 分析查询性能并接收优化建议
- 统一接口：跨不同数据库类型的一致交互模式
- 连接管理：多个数据库连接的简单配置
当前支持的数据库
| 数据库 | 地位 | 特征 |
|---|
| MySQL | ✅ 全力支持 | 查询、事务、模式分析、性能洞察 |
| PostgreSQL | ✅ 全面支持（v9.6-17） | 查询、事务、模式分析、性能洞察 |
快速入门
使用 Docker
最快的入门方式是使用 Docker：
# Pull the latest image
docker pull freepeak/db-mcp-server:latest
# Option 1: Run with environment variables (recommended)
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
# Option 2: Override the entrypoint
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
--entrypoint /app/server \
freepeak/db-mcp-server \
-t sse -c /app/my-config.json
# Option 3: Use shell to execute the command
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
freepeak/db-mcp-server \
/bin/sh -c "/app/server -t sse -c /app/my-config.json"
注意：我们挂载到/app/my-config.json是因为容器已经在/app/config.json有一个文件。
平台支持
Docker 镜像支持多种平台：
linux/amd64 - 适用于基于 Intel/AMD 的系统（大多数 Linux/Windows 服务器和台式机）linux/arm64 - 适用于基于 ARM64 的系统（Apple Silicon Macs、ARM 服务器）
如果遇到平台不匹配错误（例如，“请求的图像平台与检测到的主机平台不匹配”），请明确指定平台：
# For Intel/AMD (x86_64) systems
docker run --platform linux/amd64 -p 9092:9092 freepeak/db-mcp-server
# For ARM64 systems (like Apple Silicon Macs)
docker run --platform linux/arm64 -p 9092:9092 freepeak/db-mcp-server
来自源
# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server
# Build the server
make build
# Run the server in SSE mode
./bin/server -t sse -c config.json
运行服务器
服务器支持多种传输模式以适应不同的用例：
STDIO 模式（用于 IDE 集成）
非常适合与 AI 编码助手集成：
# Run the server in STDIO mode
./server -t stdio -c config.json
输出将作为 JSON-RPC 消息发送到 stdout，而日志将发送到 stderr。
对于 Cursor 集成，请将其添加到您的.cursor/mcp.json中：
{
"mcpServers": {
"stdio-db-mcp-server": {
"command": "/path/to/db-mcp-server/server",
"args": ["-t", "stdio", "-c", "/path/to/config.json"]
}
}
}
SSE 模式（服务器发送事件）
对于基于 Web 的应用程序和服务：
# Run with default host (localhost) and port (9092)
./server -t sse -c config.json
# Specify a custom host and port
./server -t sse -host 0.0.0.0 -port 8080 -c config.json
将您的客户端连接到http://localhost:9092/sse以获取事件流。
Docker Compose
对于带有数据库容器的开发环境，我们提供了完整的docker-compose.yml文件：
services:
db-mcp-server:
image: freepeak/db-mcp-server:latest
ports:
- "9092:9092"
volumes:
- ./config.json:/app/config.json
- ./wait-for-it.sh:/app/wait-for-it.sh
command:
[
"/bin/sh",
"-c",
"chmod +x /app/wait-for-it.sh && /app/wait-for-it.sh mysql1:3306 -t 60 && /app/wait-for-it.sh mysql2:3306 -t 60 && /app/wait-for-it.sh postgres1:5432 -t 60 && /app/wait-for-it.sh postgres3:5432 -t 60 && /app/server -t sse -c /app/config.json",
]
depends_on:
mysql1:
condition: service_healthy
mysql2:
condition: service_healthy
postgres1:
condition: service_healthy
postgres2:
condition: service_healthy
postgres3:
condition: service_healthy
mysql1:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: db1
MYSQL_USER: user1
MYSQL_PASSWORD: password1
MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password
ports:
- "13306:3306"
volumes:
- mysql1_data:/var/lib/mysql
command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost",
"-u",
"root",
"-ppassword",
]
interval: 5s
timeout: 5s
retries: 10
mysql2:
image: mysql:8.0
environment:
MYSQL_ROOT_PASSWORD: password
MYSQL_DATABASE: db2
MYSQL_USER: user2
MYSQL_PASSWORD: password2
MYSQL_AUTHENTICATION_PLUGIN: mysql_native_password
ports:
- "13307:3306"
volumes:
- mysql2_data:/var/lib/mysql
command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
healthcheck:
test:
[
"CMD",
"mysqladmin",
"ping",
"-h",
"localhost",
"-u",
"root",
"-ppassword",
]
interval: 5s
timeout: 5s
retries: 10
postgres1:
image: postgres:15
environment:
POSTGRES_USER: user1
POSTGRES_PASSWORD: password1
POSTGRES_DB: db1
ports:
- "15432:5432"
volumes:
- postgres1_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user1 -d db1"]
interval: 5s
timeout: 5s
retries: 10
postgres2:
image: postgres:17
environment:
POSTGRES_USER: user2
POSTGRES_PASSWORD: password2
POSTGRES_DB: db2
ports:
- "15433:5432"
volumes:
- postgres2_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U user2 -d db2"]
interval: 5s
timeout: 5s
retries: 10
postgres3:
image: postgres:16.3-alpine
environment:
POSTGRES_USER: screener
POSTGRES_PASSWORD: screenerpass
POSTGRES_DB: screenerdb
ports:
- "15434:5432"
volumes:
- postgres_screener_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U screener -d screenerdb"]
interval: 5s
timeout: 5s
retries: 10
volumes:
mysql1_data:
mysql2_data:
postgres1_data:
postgres2_data:
postgres_screener_data:
此 docker-compose 设置的主要特点：
- db-mcp-server 容器等待所有数据库服务准备就绪后再启动
- 包含多种数据库类型和版本（MySQL 8.0、PostgreSQL 15、16.3 和 17）
- 所有数据库都包含健康检查，以确保它们在服务器连接之前已完全初始化
- 所有数据库服务的持久卷
- 如果需要，可以公开端口用于直接访问数据库
该安装程序使用wait-for-it.sh脚本来确保在启动服务器之前所有数据库服务都已完全准备就绪。此脚本会在继续操作之前检查 TCP 主机/端口是否可用。您需要将此脚本添加到项目目录中。Docker 安装程序会将此脚本挂载到容器中，并使用它来验证数据库的可用性。
要使用此设置：
# Start all services
docker-compose up -d
# Check logs
docker-compose logs -f db-mcp-server
# Stop all services
docker-compose down
确保您的 config.json 文件包含与 docker-compose.yml 中定义的服务匹配的连接详细信息。
配置
数据库配置
使用数据库连接创建一个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": "mysql2",
"type": "mysql",
"host": "mysql2",
"port": 3306,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "postgres1",
"type": "postgres",
"host": "postgres1",
"port": 5432,
"name": "db1",
"user": "user1",
"password": "password1"
},
{
"id": "postgres2",
"type": "postgres",
"host": "postgres2",
"port": 5432,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "postgres3",
"type": "postgres",
"host": "postgres3",
"port": 5432,
"name": "screenerdb",
"user": "screener",
"password": "screenerpass"
}
]
}
使用 docker-compose 设置时，请注意host值应与 docker-compose.yml 文件中的服务名称匹配。
命令行选项
该服务器支持各种命令行选项：
# Basic options
./server -t <transport> -c <config-file>
# Available transports: stdio, sse
# For SSE transport, additional options:
./server -t sse -host <hostname> -port <port> -c <config-file>
# Direct database configuration:
./server -t stdio -db-config '{"connections":[...]}'
# Environment variable configuration:
export DB_CONFIG='{"connections":[...]}'
./server -t stdio
可用工具
对于每个连接的数据库（例如“mysql1”，“mysql2”），服务器创建：
工具命名约定
服务器自动生成名称遵循以下格式的工具：
<tool_type>_<database_id>
在哪里：
<tool_type> ：以下之一：查询、执行、事务、模式、性能<database_id> ：配置中定义的数据库的 ID
ID 为“mysql1”的数据库的示例工具名称：
query_mysql1execute_mysql1transaction_mysql1schema_mysql1performance_mysql1
数据库专用工具
query_<dbid> ：在指定的数据库上执行 SQL 查询{
"query": "SELECT * FROM users WHERE age > ?",
"params": [30]
}
execute_<dbid> ：执行 SQL 语句（INSERT、UPDATE、DELETE）{
"statement": "INSERT INTO users (name, email) VALUES (?, ?)",
"params": ["John Doe", "john@example.com"]
}
transaction_<dbid> ：管理数据库事务// Begin transaction
{
"action": "begin",
"readOnly": false
}
// Execute within transaction
{
"action": "execute",
"transactionId": "<from begin response>",
"statement": "UPDATE users SET active = ? WHERE id = ?",
"params": [true, 42]
}
// Commit transaction
{
"action": "commit",
"transactionId": "<from begin response>"
}
schema_<dbid> ：获取数据库架构信息{
"random_string": "dummy"
}
performance_<dbid> ：分析查询性能{
"action": "analyzeQuery",
"query": "SELECT * FROM users WHERE name LIKE ?"
}
全球工具
list_databases ：列出所有已配置的数据库连接
示例
查询多个数据库
// Query the first database
{
"name": "query_mysql1",
"parameters": {
"query": "SELECT * FROM users LIMIT 5"
}
}
// Query the second database
{
"name": "query_mysql2",
"parameters": {
"query": "SELECT * FROM products LIMIT 5"
}
}
执行交易
// Begin transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "begin"
}
}
// Response contains transactionId
// Execute within transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "execute",
"transactionId": "tx_12345",
"statement": "INSERT INTO orders (user_id, product_id) VALUES (?, ?)",
"params": [1, 2]
}
}
// Commit transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "commit",
"transactionId": "tx_12345"
}
}
路线图
我们致力于扩展 DB MCP Server 以支持各种数据库系统：
2025 年第三季度
- **MongoDB——**支持面向文档的数据库操作
- SQLite - 轻量级嵌入式数据库集成
- MariaDB - 与 MySQL 实现完全一致的功能
2025 年第四季度
- Microsoft SQL Server - 具有 T-SQL 功能的企业数据库支持
- Oracle 数据库- 企业级集成
- Redis - 键值存储操作
2026
- Cassandra - 分布式 NoSQL 数据库支持
- Elasticsearch - 专业搜索和分析功能
- CockroachDB - 适用于全球规模应用程序的分布式 SQL 数据库
- DynamoDB - AWS 原生 NoSQL 数据库集成
- Neo4j - 图形数据库支持
- ClickHouse - 分析数据库支持
故障排除
常见问题
- 连接错误：验证
config.json中的数据库连接设置 - 未找到工具：确保服务器正在运行并检查工具名称前缀
- 失败的查询：检查您的 SQL 语法和数据库权限
- Docker 卷挂载错误：如果您看到类似
mountpoint for /app/config.json: not a directory错误，那是因为容器在该路径下已经有一个文件。请挂载到其他路径（例如， /app/my-config.json my-config.json），并相应地更新您的配置。 - Docker 命令错误：如果您遇到与 Docker 命令相关的错误，请使用以下方法之一：
- 使用环境变量：
-e TRANSPORT_MODE=sse -e CONFIG_PATH=/app/my-config.json - 覆盖入口点：
--entrypoint /app/server freepeak/db-mcp-server -t sse -c /app/my-config.json - 使用shell执行：
freepeak/db-mcp-server /bin/sh -c "/app/server -t sse -c /app/my-config.json"
- Wait-for-it.sh 缺失或不工作：如果您看到与 wait-for-it.sh 相关的错误：
- 确保文件存在于您的项目目录中
- 确保它具有可执行权限：
chmod +x wait-for-it.sh - 检查正确的行尾（使用 Unix 风格的 LF，而不是 Windows 风格的 CRLF）
- 如果仍然遇到问题，您可以修改 docker-compose.yml 以使用服务健康检查
日志
服务器将日志写入：
- STDIO 模式：stderr
- SSE 模式：stdout 和
./logs/db-mcp-server.log
使用-debug标志启用调试日志记录：
./server -t sse -debug -c config.json
贡献
欢迎贡献！您可以通过以下方式提供帮助：
- 分叉存储库
- 创建功能分支：
git checkout -b new-feature - 提交您的更改：
git commit -am 'Add new feature' - 推送到分支：
git push origin new-feature - 提交拉取请求
请确保您的代码符合我们的编码标准并包含适当的测试。
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。
支持与联系方式
光标集成
工具命名约定
MCP 服务器会注册符合 Cursor 期望格式的工具名称。工具名称遵循以下格式：
mcp_<servername>_<tooltype>_<dbID>
例如： mcp_mysql1_db_mcp_server_stdio_schema_mysql1_db
服务器默认使用名称mysql1_db_mcp_server_stdio ，该名称应与mcp.json文件中的 Cursor 配置相匹配。
游标配置
在您的 Cursor 配置（ ~/.cursor/mcp.json ）中，您应该有如下配置：
{
"mcpServers": {
"multidb": {
"command": "/path/to/db-mcp-server/server",
"args": ["-t", "stdio", "-c", "/path/to/database_config.json"]
}
}
}
服务器将自动注册与您配置中的数据库标识符匹配的简单名称的工具。
在 Cursor 中使用 MCP 工具
一旦您的 DB MCP 服务器在 Cursor 中运行并正确配置，您就可以在 AI 助手对话中使用 MCP 工具。这些工具遵循以下命名模式：
mcp_<server_name>_<tool_type>_<database_id>
在哪里：
<server_name>是 .cursor/mcp.json 中定义的名称（例如“multidb”）<tool_type>是以下之一：查询、执行、事务、模式、性能、list_databases<database_id>是您配置中的数据库 ID（list_databases 不需要）
例子：
对于名为“multidb”且数据库 ID 为“mysql1”的服务器：
- 列出所有数据库：
mcp_multidb_list_databases
- 查询数据库：
mcp_multidb_query_mysql1
Query: SELECT * FROM users LIMIT 10
- 查看数据库模式：
mcp_multidb_schema_mysql1
- 执行语句：
mcp_multidb_execute_mysql1
Statement: INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')
- 管理交易：
mcp_multidb_transaction_mysql1
Action: begin
Cursor 中的 MCP 工具故障排除
如果AI助手无法调用MCP工具：
- 确保服务器正在运行（使用
ps aux | grep server检查） - 验证你的 .cursor/mcp.json 配置是否正确
- 确保 .env 中的 server_name 与 MCP 工具调用中的内容匹配
- 更改配置后重新启动 Cursor
- 检查 logs/ 目录中的日志是否有任何错误
OpenAI Agents SDK 集成
DB MCP 服务器完全支持 OpenAI 的 Agents SDK，允许您创建可以直接与数据库交互的 AI 代理。
先决条件
- 具有 API 访问权限的 OpenAI 帐户
- OpenAI Agents SDK 安装：
pip install openai-agents - 正在运行的 DB MCP 服务器实例（SSE 模式）
基本集成示例
以下是将 DB MCP 服务器与 OpenAI 代理集成的方法：
from openai import OpenAI
from agents.agent import Agent, ModelSettings
from agents.tools.mcp_server import MCPServerSse, MCPServerSseParams
# Connect to the MCP server
db_server = MCPServerSse(
params=MCPServerSseParams(
url="http://localhost:9095/sse", # URL to your running DB MCP server
schema={
"params": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {"type": "string"},
"description": {"type": "string"},
"parameters": {"type": "object"}
}
}
}
}
),
)
# Create the agent with access to database tools
agent = Agent(
name="Database Agent",
model="gpt-4o",
model_settings=ModelSettings(temperature=0.1),
instructions="""
You are a database helper agent. You can execute SQL queries,
manage database transactions, and explore schema information.
""",
mcp_servers=[db_server],
)
# Now the agent can be used to interact with your databases through the OpenAI API
测试您的集成
该存储库包含一个测试脚本，用于验证与 OpenAI Agents SDK 的兼容性：
# Run the test script
./test_tools/openai-agent-sdk-test/run_test.sh
该脚本将：
- 使用最新的更改构建服务器
- 如果服务器尚未运行，请启动它
- 测试与 OpenAI Agents SDK 的连接
- 报告集成是否正常运行
Agents SDK 集成故障排除
如果您遇到问题：
- 确保服务器在预期端口上以 SSE 模式运行
- 检查您的 OpenAI API 密钥是否已设置为环境变量
- 确认您的代理的说明中具体提到了数据库工具
- 检查服务器日志中是否有任何错误消息
星史
数据库查询超时配置
您可以在config.json文件中为每个数据库连接配置数据库查询超时时间。超时时间以秒为单位。
示例配置：
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "mysql1",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1",
"query_timeout": 60, // 60 seconds timeout for queries
"max_open_conns": 20,
"max_idle_conns": 5,
"conn_max_lifetime_seconds": 300,
"conn_max_idle_time_seconds": 60
}
]
}
如果未指定，默认查询超时时间为 30 秒。您可以在执行查询时指定timeout参数（以毫秒为单位），以覆盖单个查询的超时设置。
{
"tool": "query_mysql",
"params": {
"query": "SELECT * FROM large_table",
"database": "mysql1",
"timeout": 120000 // 120 seconds (overrides the database configuration)
}
}