简介

多数据库MCP服务器是数据库模型上下文协议的高性能实现，旨在革新AI代理与数据库交互的方式。目前支持MySQL和PostgreSQL数据库。

简介

多数据库MCP服务器是数据库模型上下文协议的高性能实现，旨在革新AI代理与数据库交互的方式。目前支持MySQL和PostgreSQL数据库。

什么是DB MCP服务器？

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"
    }
  ]
}

动态工具生成

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

// 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

清晰架构

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

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

特性

• 同时支持多个数据库: 同时连接和交互多个 MySQL 和 PostgreSQL 数据库
• 特定数据库工具生成: 为每个连接的数据库自动生成专门的工具
• 清晰的架构: 模块化设计，职责分明
• OpenAI Agents SDK 兼容性: 完全兼容 OpenAI Agents SDK，可无缝集成 AI 助手
• 动态数据库工具:
  • 执行带参数的 SQL 查询
  • 运行数据修改语句并进行适当的错误处理
  • 跨会话管理数据库事务
  • 探索数据库模式和关系
  • 分析查询性能并接收优化建议
• 统一界面: 在不同类型的数据库之间保持一致的交互模式
• 连接管理: 简单配置多个数据库连接

当前支持的数据库

快速开始

使用 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 消息的形式发送到标准输出，而日志则发送到标准错误输出。

对于 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
version: '3'
services:
  db-mcp-server:
    image: freepeak/db-mcp-server:latest
    ports:
      - "9092:9092"
    volumes:
      - ./config.json:/app/my-config.json
    environment:
      - TRANSPORT_MODE=sse
      - CONFIG_PATH=/app/my-config.json
    # Alternative using entrypoint
    # entrypoint: ["/app/server"]
    # command: ["-t", "sse", "-c", "/app/my-config.json"]
    depends_on:
      - mysql
      - postgres
  
  mysql:
    image: mysql:8
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: testdb
      MYSQL_USER: user
      MYSQL_PASSWORD: password
    ports:
      - "3306:3306"
  
  postgres:
    image: postgres:17
    environment:
      POSTGRES_DB: testdb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    ports:
      - "5432:5432"

配置

数据库配置

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

{
  "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"
    }
  ]
}

命令行选项

服务器支持各种命令行选项：

# 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>: 一种：query, execute, transaction, schema, performance
• <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>: 管理数据库事务

  // 开始事务
  {
    "action": "begin",
    "readOnly": false
  }
  
  // 在事务中执行
  {
    "action": "execute",
    "transactionId": "<from begin response>",
    "statement": "UPDATE users SET active = ? WHERE id = ?",
    "params": [true, 42]
  }
  
  // 提交事务
  {
    "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 Database - 企业级集成
• Redis - 键值存储操作

2026 年

• Cassandra - 分布式 NoSQL 数据库支持
• Elasticsearch - 专门的搜索和分析功能
• CockroachDB - 适用于全球规模应用的分布式 SQL 数据库
• DynamoDB - AWS 原生 NoSQL 数据库集成
• Neo4j - 图数据库支持
• ClickHouse - 分析数据库支持

故障排除

常见问题

1. 连接错误：请检查 config.json 中的数据库连接设置
2. 找不到工具：确保服务器正在运行，并检查工具名称前缀
3. 查询失败：检查您的 SQL 语法和数据库权限
4. Docker 卷挂载错误：如果您看到类似 mountpoint for /app/config.json: not a directory 的错误，这是因为容器在该路径下已经有一个文件。将卷挂载到不同的路径（例如 /app/my-config.json），并相应地更新配置。
5. 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"

日志

服务器将日志写入：

• STDIO 模式：stderr
• SSE 模式：stdout 和 ./logs/db-mcp-server.log

启用调试日志记录，使用 -debug 标志：

./server -t sse -debug -c config.json

贡献

欢迎贡献！以下是您可以帮助的方式：

1. 分叉 仓库
2. 创建 功能分支：git checkout -b new-feature
3. 提交 您的更改：git commit -am 'Add new feature'
4. 推送 到分支：git push origin new-feature
5. 提交 拉取请求

请确保您的代码遵循我们的编码标准，并包含适当的测试。

许可证

本项目根据 MIT 许可证许可 - 有关详细信息，请参阅 LICENSE 文件。

支持与联系

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

Cursor 集成

工具命名约定

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 配置（~/.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 Server 正在运行并在 Cursor 中正确配置，您可以在 AI 助手对话中使用这些 MCP 工具。工具遵循以下命名模式：

mcp_<server_name>_<tool_type>_<database_id>

其中：

• <server_name> 是你在 .cursor/mcp.json 中定义的名称（例如："multidb"）
• <tool_type> 是以下之一：query, execute, transaction, schema, performance, list_databases
• <database_id> 是你的配置中的数据库 ID（list_databases 不需要）

示例：

对于名为 "multidb" 且数据库 ID 为 "mysql1" 的服务器：

1. 列出所有数据库：

mcp_multidb_list_databases

2. 查询数据库：

mcp_multidb_query_mysql1
Query: SELECT * FROM users LIMIT 10

3. 查看数据库模式：

mcp_multidb_schema_mysql1

4. 执行语句：

mcp_multidb_execute_mysql1
Statement: INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')

5. 管理事务：

mcp_multidb_transaction_mysql1
Action: begin

在 Cursor 中排查 MCP 工具问题

如果 AI 助手无法调用 MCP 工具：

1. 确保服务器正在运行（使用 ps aux | grep server 检查）
2. 验证 .cursor/mcp.json 配置是否正确
3. 确保 .env 文件中的 server_name 与 MCP 工具调用中的名称匹配
4. 在进行配置更改后重启 Cursor
5. 检查 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 Agent 集成的方法：

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

该脚本将：

1. 使用最新更改构建服务器
2. 如果服务器未运行，则启动服务器
3. 使用 OpenAI Agents SDK 测试连接
4. 报告集成是否正常工作

排查 Agents SDK 集成问题

如果你遇到问题：

1. 确保服务器以 SSE 模式在预期端口上运行
2. 检查是否已将 OpenAI API 密钥设置为环境变量
3. 确认你的代理指令明确提到数据库工具
4. 检查服务器日志中的任何错误消息

服务配置

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

来源

• 来源：github
• 链接：https://github.com/FreePeak/db-mcp-server