多数据库 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文件。如果遇到平台不匹配警告，可以指定平台： --platform linux/amd64或--platform linux/arm64 。

来自源

# 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
./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
      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"
    },
    {
      "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_mysql1
execute_mysql1
transaction_mysql1
schema_mysql1
performance_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 文件。

支持与联系方式

如有任何疑问或问题，请发送电子邮件至mnhatlinh.doan@gmail.com
直接打开问题：问题跟踪器
如果 DB MCP Server 对您的工作有帮助，请考虑支持：

光标集成

工具命名约定

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 密钥是否已设置为环境变量
确认您的代理的说明中具体提到了数据库工具
检查服务器日志中是否有任何错误消息

Integrations

多数据库 MCP 服务器

什么是 DB MCP 服务器？

核心概念

多数据库支持

动态工具生成

清洁架构

特征

当前支持的数据库

快速入门

使用 Docker

来自源

运行服务器

STDIO 模式（用于 IDE 集成）

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

Docker Compose

配置

数据库配置

命令行选项

可用工具

工具命名约定

数据库专用工具

全球工具

示例

查询多个数据库

执行交易

路线图

2025 年第三季度

2025 年第四季度

2026

故障排除

常见问题

日志

贡献

执照

支持与联系方式

光标集成

工具命名约定

游标配置

在 Cursor 中使用 MCP 工具

例子：

Cursor 中的 MCP 工具故障排除

OpenAI Agents SDK 集成

先决条件

基本集成示例

测试您的集成

Agents SDK 集成故障排除

星史

Appeared in Searches