DB Connect MCP

db-connect-mcp - 多数据库 MCP 服务

一个只读 MCP（Model Context Protocol）服务，用于跨多个数据库系统进行探索性数据分析。此服务可安全、只读地访问 PostgreSQL、MySQL 和 ClickHouse 数据库，并提供全面的分析能力。

演示

快速开始

1. 安装：

   pip install db-connect-mcp
   

2. 添加到 Claude Desktop claude_desktop_config.json：

   {
     "mcpServers": {
       "db-connect": {
         "command": "python",
         "args": ["-m", "db_connect_mcp"],
         "env": {
           "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
         }
       }
     }
   }
   

3. 重启 Claude Desktop，开始查询数据库！

注意：使用 python -m db_connect_mcp 可确保即使 Python 的 Scripts 目录不在 PATH 中，命令也能正常运行。现有的 mcpServers 配置仍然有效：stdio 仍是默认方式。可选的远程 Streamable HTTP 模式会在 /mcp 提供服务，兼容较早的基于 initialize 的客户端，以及 2026-07-28 无会话 MCP 客户端，且无需更改数据库或 SSH 配置。现有 HTTP 部署必须检查转发的 Host/Origin 值：此次升级启用了传输验证，可能需要设置 MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS。

功能

🗄️ 多数据库支持

• PostgreSQL - 完整支持，提供高级元数据和统计信息
• MySQL - 完整支持 MySQL 和 MariaDB 数据库
• ClickHouse - 支持分析型工作负载和列式存储

🔍 数据库探索

• 列出架构 - 查看数据库中的所有架构
• 列出表 - 查看所有表及其元数据（大小、行数、注释）
• 描述表 - 获取详细的列信息、索引和约束
• 查看关系 - 了解表之间的外键关系

📊 数据分析

• 列分析 - 对列数据进行统计分析
  • 基本统计信息（计数、唯一值、空值）
  • 数值统计信息（平均值、中位数、标准差、四分位数）
  • 值频率分布
  • 基数分析
• 数据采样 - 通过可配置的限制预览表数据
• 自定义查询 - 安全地执行只读 SQL 查询
• 对象搜索 - 无需加载完整目录即可查找架构、表、视图、列和索引
• 查询计划 - 检查预估计划，或选择使用受支持的 EXPLAIN ANALYZE
• 假设索引（PostgreSQL，可选启用） - 比较 HypoPG 规划器的估算，而不创建真实索引。需要由管理员安装 HypoPG 扩展、在服务端设置 DB_HYPOPG_ENABLED=true，并在每次 compare_hypothetical_index 调用中设置 opt_in=true。请提供单条简单的 SELECT、架构、表以及 1–4 个列名；注释、CTE、函数、字面值、参数和多条语句都会被拒绝。该工具使用一个只读连接和不带 ANALYZE 的 EXPLAIN，将规划/锁等待时间分别限制为 5s/1s，并回滚仅限会话的更改。响应通过匹配结果计划中的 HypoPG 索引名称来报告 hypothetical_index_used；未使用候选索引可能无关紧要，也可能只是规划器没有选择它。候选索引要求具备架构 USAGE 和表 SELECT 权限。这些估算并非实际测得的加速效果。

🔒 安全功能

• 强制只读 - 所有连接都在多个层面上强制为只读
• 查询验证 - 仅允许 SELECT 和 WITH 查询
• 自动限制 - 自动限制查询结果，防止返回过大的结果集
• 连接字符串安全 - 自动添加只读参数
• 数据库专属安全措施 - 每个适配器都会实施适当的安全措施

🔭 可观测性

db-connect-mcp 继承了 MCP SDK 内置的 OpenTelemetry 服务端 监控功能。只有启动进程配置了 SDK 和导出器后，API 才会启用。生产环境使用前， 请检查导出器的采样和脱敏设置，因为数据库标识符和错误详情可能包含敏感信息。

💡 最佳实践

提示： 为表和列添加了适当注释的数据库最适合搭配 db-connect-mcp 使用。当数据库包含描述性注释时，MCP 服务可以向 AI 助手提供更丰富的上下文，帮助它们更好地理解数据模型，并提供更准确的查询建议。

在 PostgreSQL 中添加注释：

COMMENT ON TABLE users IS 'Registered user accounts with profile information';
COMMENT ON COLUMN users.email IS 'Primary email address, used for authentication';
COMMENT ON COLUMN users.is_verified IS 'Whether email has been verified via confirmation link';

在 MySQL 中添加注释：

ALTER TABLE users COMMENT = 'Registered user accounts with profile information';
ALTER TABLE users MODIFY COLUMN email VARCHAR(255) COMMENT 'Primary email address, used for authentication';

描述表时，服务会自动检索并显示这些注释，帮助 AI 助手理解数据的用途和语义。

🔐 SSH 隧道支持

• 安全远程访问 - 通过 SSH 隧道连接到防火墙后的数据库
• 自动管理隧道 - 透明地处理隧道生命周期（启动、健康检查、重启、清理）
• 可靠的原生转发 - 使用 Paramiko SSHClient 传输，并进行目标预检和稳定端口恢复
• 灵活的身份验证 - 支持基于密码或私钥的 SSH 身份验证
• 适用于任何数据库类型 - 可通过同一隧道连接 PostgreSQL、MySQL 和 ClickHouse

配置详情请参阅 SSH 隧道指南。

安装

前置条件

• Python 3.10 或更高版本
• 数据库：PostgreSQL（9.6+）、MySQL/MariaDB（5.7+/10.2+）或 ClickHouse

通过 pip 安装

pip install db-connect-mcp

完成！现在可以使用此软件包了。

开发者须知：有关如何设置开发环境，请参阅开发指南。

配置

创建 .env 文件，并填入数据库连接字符串：

DATABASE_URL=your_database_connection_string_here

服务会自动检测数据库类型，并添加相应的只读参数。

对于 PostgreSQL，设置 ENABLE_PG_STAT_STATEMENTS=true 可启用并公布可选的 get_top_queries 工具。如果数据库管理员已安装并预加载 pg_stat_statements，该工具会读取当前用户和数据库的有限累计统计数据。它不会安装扩展。除非明确请求，否则不会包含查询文本；查询文本可能包含敏感信息。有关限制和状态，请参阅热门查询报告规范。

连接字符串示例

服务器现在提供更灵活、更安全的 URL 处理方式：

• 自动检测驱动程序：如果未指定异步驱动程序，则会自动添加
• 支持 JDBC URL：自动处理 JDBC 前缀
  • jdbc:postgresql://... → postgresql+asyncpg://...
  • jdbc:mysql://... → mysql+aiomysql://...
  • 适用于所有方言变体（例如 jdbc:postgres://、jdbc:mariadb://）
• 数据库方言变体：自动规范化常见变体
  • PostgreSQL：postgresql、postgres、pg、psql、pgsql
  • MySQL/MariaDB：mysql、mariadb、maria
  • ClickHouse：clickhouse、ch、click
• 基于允许列表的参数过滤：仅保留已知安全的参数
• 数据库专属参数：每种数据库类型都有各自支持的参数
• 健壮的解析：能够妥善处理各种 URL 格式

PostgreSQL：

# Simple URL (driver automatically added)
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Common variations (all normalized to postgresql+asyncpg)
DATABASE_URL=postgres://user:pass@host:5432/db  # Heroku, AWS RDS style
DATABASE_URL=pg://user:pass@host:5432/db         # Short form
DATABASE_URL=psql://user:pass@host:5432/db       # CLI style

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:postgresql://user:pass@host:5432/db  # From Java apps
DATABASE_URL=jdbc:postgres://user:pass@host:5432/db    # JDBC with variant

# With explicit async driver
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db

# With supported parameters (see list below)
DATABASE_URL=postgres://user:pass@host:5432/db?application_name=myapp&connect_timeout=10

支持的 PostgreSQL 参数：

• application_name - 标识 pg_stat_activity 中的应用（便于监控）
• connect_timeout - 连接超时时间，单位为秒
• command_timeout - 操作的默认超时时间
• ssl / sslmode - SSL 连接要求（会自动转换为兼容 asyncpg 的格式）
• server_settings - 服务器设置字典
• options - 要发送给服务器的命令行选项
• 性能调优：prepared_statement_cache_size、max_cached_statement_lifetime 等

MySQL/MariaDB：

# Simple URL (driver automatically added)
DATABASE_URL=mysql://root:password@localhost:3306/mydb

# MariaDB URLs (normalized to mysql+aiomysql)
DATABASE_URL=mariadb://user:pass@host:3306/db    # MariaDB style
DATABASE_URL=maria://user:pass@host:3306/db      # Short form

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:mysql://user:pass@host:3306/db     # From Java apps
DATABASE_URL=jdbc:mariadb://user:pass@host:3306/db   # JDBC MariaDB

# With explicit async driver
DATABASE_URL=mysql+aiomysql://user:pass@host:3306/db

# With charset (critical for proper Unicode support)
DATABASE_URL=mariadb://user:[email protected]:3306/db?charset=utf8mb4

支持的 MySQL 参数：

• charset - 字符编码（例如 utf8mb4）- 对数据完整性至关重要
• use_unicode - 启用 Unicode 支持
• connect_timeout、read_timeout、write_timeout - 各种超时设置
• autocommit - 事务自动提交模式
• init_command - 要运行的初始 SQL 命令
• sql_mode - SQL 模式设置
• time_zone - 时区设置

ClickHouse：

# Simple URL (driver automatically added)
DATABASE_URL=clickhouse://default:@localhost:9000/default

# Short forms (normalized to clickhouse+asynch)
DATABASE_URL=ch://user:pass@host:9000/db         # Short form
DATABASE_URL=click://user:pass@host:9000/db      # Alternative

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:clickhouse://user:pass@host:9000/db  # From Java apps
DATABASE_URL=jdbc:ch://user:pass@host:9000/db         # JDBC with short form

# With explicit async driver
DATABASE_URL=clickhouse+asynch://user:pass@host:9000/db

# With performance settings
DATABASE_URL=ch://user:pass@host:9000/db?timeout=60&max_threads=4

支持的 ClickHouse 参数：

• database - 默认数据库选择
• timeout、connect_timeout、send_receive_timeout - 各种超时设置
• compress、compression - 启用压缩
• max_block_size、max_threads - 性能调优

注意：

• SSL 参数（ssl、sslmode）会自动转换为适用于 asyncpg 的正确格式
• 证书文件参数（sslcert、sslkey、sslrootcert）会被过滤，因为它们可能导致兼容性问题
• 仅保留已知可与异步驱动程序配合使用的参数

使用方法

运行服务器

# Run the server (works everywhere, no PATH configuration needed)
python -m db_connect_mcp

# With environment variable
DATABASE_URL="postgresql://user:pass@host:5432/db" python -m db_connect_mcp

注意：无论 Python 的 Scripts 目录是否在 PATH 中，使用 python -m db_connect_mcp 都可以正常运行。

与 Claude Code 搭配使用

将 MCP 服务添加到项目的 .mcp.json 中：

claude mcp add --transport stdio db-connect --scope project \
  --env DATABASE_URL=postgresql://user:pass@host:5432/db \
  -- python -m db_connect_mcp

也可以在项目根目录中手动创建 .mcp.json。以下是各受支持数据库的示例：

PostgreSQL：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/mydb"
      }
    }
  }
}

MySQL：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@host:3306/mydb"
      }
    }
  }
}

ClickHouse：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "clickhouse+asynch://default:@host:9000/default"
      }
    }
  }
}

通过 SSH 隧道连接 PostgreSQL（数据库位于防火墙后，只能通过堡垒主机访问）：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@db-internal:5432/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/id_rsa"
      }
    }
  }
}

通过 SSH 隧道连接 MySQL：

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@db-internal:3306/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PASSWORD": "secret"
      }
    }
  }
}

多个数据库（每个 MCP 服务实例连接一个数据库）：

{
  "mcpServers": {
    "postgres-prod": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@pg-host:5432/prod"
      }
    },
    "mysql-analytics": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@mysql-host:3306/analytics"
      }
    }
  }
}

创建 .mcp.json 后，重启 Claude Code 并使用 /mcp 验证。你应该会看到 db-connect-mcp，其中列出了所有可用工具。

**提示：**你可以使用 SSH_PRIVATE_KEY 直接以字符串形式传递私钥内容（原始 PEM 或 Base64 编码的 PEM），而不使用 SSH_PRIVATE_KEY_PATH。这适用于挂载密钥文件不切实际的 CI/CD 或云环境。

完整的隧道配置参考，请参阅 SSH 隧道指南。

与 Claude Desktop 配合使用

将服务添加到 Claude Desktop 配置（claude_desktop_config.json）中：

{
  "mcpServers": {
    "db-connect": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/db"
      }
    }
  }
}

上方 Claude Code 示例中展示的相同数据库 URL 格式和 SSH 隧道环境变量，也同样适用于 Claude Desktop。

开发：请参阅开发指南，了解如何使用 uv 从源代码运行。

数据库功能支持

功能	PostgreSQL	MySQL	ClickHouse
架构	✅ 完整	✅ 完整	✅ 完整
表	✅ 完整	✅ 完整	✅ 完整
视图	✅ 完整	✅ 完整	✅ 完整
索引	✅ 完整	✅ 完整	⚠️ 有限
外键	✅ 完整	✅ 完整	❌ 不支持
约束	✅ 完整	✅ 完整	⚠️ 有限
表大小	✅ 精确	✅ 精确	✅ 精确
行数	✅ 精确	✅ 精确	✅ 精确
列统计信息	✅ 完整	✅ 完整	✅ 完整
采样	✅ 完整	✅ 完整	✅ 完整

MCP 资源

现代 MCP 客户端除了调用工具外，还可以将数据库上下文发现为私有、支持缓存的 JSON 资源：

• db-connect://database — 数据库标识、方言和功能
• db-connect://schema/{schema} — 架构计数和元数据
• db-connect://table/{schema}/{table} — 列、索引、约束和注释

如果已知标识符，也会将架构和表形式作为资源模板发布，以便直接访问。

资源目录按 URI 排序，并以每页 100 条的方式通过游标分页。游标与目录快照绑定；如果架构或表在分页期间发生变化，服务会要求客户端重新开始分页，而不是返回不一致的遍历结果。

可用工具

所有工具均提供 JSON Schema 输入和输出契约、只读行为注释以及机器可读的结构化结果。对于尚未使用 MCP 结构化内容的客户端，也可以通过 JSON 文本获取相同结果。结构化列表结果使用 items 封装，而其旧版文本形式仍为 JSON 数组。

get_database_info

获取数据库元数据，包括方言、版本、连接详情、只读状态和功能。

list_schemas

列出数据库中的所有架构。

list_tables

列出架构中的所有表及其元数据。

• 参数：
  • schema（可选）：架构名称（默认值：“public”）

describe_table

获取表的详细信息。

• 参数：
  • table：表名称
  • schema（可选）：架构名称（默认值：“public”）

analyze_column

分析列的统计信息和分布情况。

• 参数：
  • table：表名称
  • column：列名称
  • schema（可选）：架构名称（默认值：“public”）

sample_data

获取表中的数据样本。

• 参数：
  • table：表名称
  • schema（可选）：架构名称（默认值：“public”）
  • limit（可选）：行数（默认值：100，最大值：1000）

execute_query

执行只读 SQL 查询。

• 参数：
  • query：SQL 查询（必须为 SELECT 或 WITH）
  • limit（可选）：最大行数（默认值：1000，最大值：10000）

get_table_relationships

获取表的外键关系。

• 参数：
  • table：表名称
  • schema（可选）：架构名称（默认值：“public”）

explain_query

获取数据库专属的查询执行计划。

• 参数：
  • query：要解释的 SQL 查询
  • analyze（可选）：执行查询并包含实际运行时统计信息（默认值：false）

search_objects

以渐进式详细程度搜索架构、表、视图、列和索引。

• 参数：
  • pattern：SQL LIKE 模式，例如 %user%
  • object_types（可选）：要包含的对象类型
  • detail_level（可选）：names、summary 或 full（默认值：summary）
  • schema（可选）：将搜索范围限制在某个架构内
  • table（可选）：将列和索引搜索范围限制在某个表内
  • limit（可选）：匹配结果上限（默认值：100，最大值：1000）

示例用法

配置完成后，即可通过任何兼容的 MCP 客户端使用该服务：

"Can you analyze my database and tell me about the table structure?"

"Show me the relationships between tables in the public schema"

"What's the distribution of values in the users.created_at column?"

"Give me a sample of data from the orders table"

"Run this query: SELECT COUNT(*) FROM users WHERE created_at > '2024-01-01'"

特定数据库示例

使用 PostgreSQL：

"List all schemas except system ones"
"Show me the foreign key relationships in the sales schema"
"Analyze the performance of indexes on the products table"

使用 MySQL：

"What storage engines are being used in my database?"
"Show me all tables in the information_schema"
"Analyze the customer_orders table structure"

使用 ClickHouse：

"Show me the partitions for the events table"
"What's the compression ratio for the analytics.clicks table?"
"Sample 1000 rows from the metrics table"

安全性

• 只读意图：写入语句会被拒绝，PostgreSQL 和 MySQL 连接会使用只读事务。这并非 SQL 沙箱：SELECT 可能会调用具有外部影响或会话级影响的函数。MySQL 只读会话不会跨请求复用；execute_query 会拒绝直接调用命名锁和变量赋值。所有数据库引擎都应使用遵循最小权限原则的数据库角色，尤其是 ClickHouse，因为 SELECT 可能会调用外部表函数。
• 查询限制：execute_query 限制返回行数和序列化响应大小，但不会限制数据库总工作量或进程峰值内存。ClickHouse 的同步驱动程序可能会先缓冲完整结果，之后应用程序才会进行检查。请使用数据库端的执行、内存和访问限制。请参阅运行状况和查询安全说明。

开发

有关详细的开发环境设置、测试和贡献指南，请参阅开发指南。

项目结构

db-connect-mcp/
├── src/
│   └── db_connect_mcp/
│       ├── adapters/         # Database-specific adapters
│       │   ├── __init__.py
│       │   ├── base.py      # Base adapter interface
│       │   ├── postgresql.py # PostgreSQL adapter
│       │   ├── mysql.py     # MySQL adapter
│       │   └── clickhouse.py # ClickHouse adapter
│       ├── core/            # Core functionality
│       │   ├── __init__.py
│       │   ├── connection.py # Database connection management
│       │   ├── executor.py  # Query execution
│       │   ├── inspector.py # Metadata inspection
│       │   ├── analyzer.py  # Statistical analysis
│       │   └── tunnel.py   # SSH tunnel management
│       ├── models/          # Data models
│       │   ├── __init__.py
│       │   ├── capabilities.py # Database capabilities
│       │   ├── config.py    # Configuration models
│       │   ├── database.py  # Database models
│       │   ├── query.py     # Query models
│       │   ├── statistics.py # Statistics models
│       │   └── table.py     # Table metadata models
│       ├── __init__.py
│       ├── __main__.py      # Module entry point
│       └── server.py        # Main MCP server implementation
├── tests/
│   ├── unit/            # Unit tests (mocked)
│   ├── module/          # Module tests (single component + DB)
│   ├── integration/     # Integration tests (full stack)
│   └── conftest.py      # Shared fixtures
├── .env.example         # Example environment configuration
├── pyproject.toml      # Project dependencies and console scripts
└── README.md          # This file

架构

该服务使用适配器模式来支持多个数据库系统：

• 适配器：每种数据库类型都有自己的适配器，用于实现特定于数据库的功能
• 核心：用于连接管理、查询执行和元数据检查的共享功能
• 模型：用于类型安全和验证的 Pydantic 模型
• 服务：MCP 服务实现，用于将请求路由到相应组件

运行测试

# Start local test database (PostgreSQL 17 with sample data)
cd tests/docker && docker-compose up -d && cd ../..

# Run all tests in parallel (preferred - 6 workers)
uv run pytest -n 6

# Run specific test modules
uv run pytest tests/module/test_inspector.py -v -n 6
uv run pytest tests/integration/ -v -n 6

# Stop test database
cd tests/docker && docker-compose down && cd ../..

# Reset database (clean slate with fresh data)
cd tests/docker && docker-compose down -v && docker-compose up -d && cd ../..

本地测试数据库：

• PostgreSQL 17，包含 7 张表、超过 5 万行的示例数据
• 通过 Docker Compose 自动初始化
• 无需云数据库或 .env 配置
• 详情请参阅 Docker 设置

有关详细的测试说明，请参阅开发指南和测试指南。

故障排除

连接问题

• 确认 DATABASE_URL 正确且包含相应的驱动程序
• 检查与数据库的网络连接
• 确保数据库用户具有相应的读取权限
• 对于 PostgreSQL：检查是否需要 SSL（?ssl=require）
• 对于 MySQL：验证字符集设置（?charset=utf8mb4）
• 对于 ClickHouse：检查端口（原生协议的默认端口为 9000，HTTP 的默认端口为 8123）

特定数据库问题

PostgreSQL：

• 确保异步操作指定了 asyncpg 驱动程序
• 云数据库可能需要 SSL 证书

MySQL/MariaDB：

• 异步支持请使用 aiomysql 驱动程序
• 检查 MySQL 版本兼容性（5.7+ 或 MariaDB 10.2+）
• 验证字符集和排序规则设置

ClickHouse：

• 异步操作请使用 asynch 驱动程序
• 请注意，ClickHouse 对外键和约束的支持有限
• 某些统计函数可能不可用

权限错误

• 数据库用户至少需要对要分析的架构/表具有 SELECT 权限
• 某些统计函数可能需要额外权限
• ClickHouse 可能需要对系统表的特定权限

大型结果集

• 使用 limit 参数控制结果大小
• 服务会自动限制结果，以避免内存问题
• 对于大型分析，请考虑使用更具体的查询

作者

由 Yuri Gui 创建。

贡献

欢迎贡献！该服务默认设计为只读且安全。任何新功能都应保持这些安全保障。

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件