shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

db-connect-mcp

一个支持多数据库的只读MCP服务器，用于跨PostgreSQL、MySQL和ClickHouse进行探索性数据分析，提供安全的只读访问和全面的分析功能。

article

README

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

db-connect-mcp是一个只读的MCP（模型上下文协议）服务器，专为跨多个数据库系统进行探索性数据分析而设计。该服务器可安全、只读地访问PostgreSQL、MySQL和ClickHouse数据库，并具备全面的分析能力。

🚀 快速开始

  1. 安装：
pip install db-connect-mcp
  1. 添加到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"
            }
        }
    }
}
  1. 重启Claude Desktop，即可开始查询数据库！

⚠️ 重要提示

使用python -m db_connect_mcp可确保即使Python的Scripts目录不在系统路径中，该命令依然可以正常工作。

✨ 主要特性

🗄️ 多数据库支持

  • PostgreSQL - 全面支持，具备高级元数据和统计功能。
  • MySQL - 完全支持MySQL和MariaDB数据库。
  • ClickHouse - 支持分析型工作负载和列式存储。

🔍 数据库探索

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

📊 数据分析

  • 列分析 - 对列数据进行统计分析：
    • 基本统计信息（计数、唯一值、空值）。
    • 数值统计信息（均值、中位数、标准差、四分位数）。
    • 值频率分布。
    • 基数分析。
  • 数据采样 - 可配置限制地预览表数据。
  • 自定义查询 - 安全地执行只读SQL查询。
  • 数据库分析 - 获取高级数据库指标和最大的表。

🔒 安全特性

  • 强制只读 - 所有连接在多个层面均为只读。
  • 查询验证 - 仅允许SELECT和WITH查询。
  • 自动限制 - 自动限制查询结果集，防止产生大量数据。
  • 连接字符串安全 - 自动添加只读参数。
  • 特定数据库安全 - 每个适配器都实现了相应的安全措施。

💡 使用建议

💡 使用建议

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隧道连接防火墙后的数据库。
  • 自动隧道管理 - 透明处理隧道的生命周期（启动、健康检查、重启、清理）。
  • 灵活认证 - 支持基于密码或私钥的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

服务器会自动检测数据库类型并添加适当的只读参数。

连接字符串示例

服务器现在提供了更灵活、安全的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：

# 简单URL（自动添加驱动）
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# 常见变体（均规范化为postgresql+asyncpg）
DATABASE_URL=postgres://user:pass@host:5432/db  # Heroku、AWS RDS风格
DATABASE_URL=pg://user:pass@host:5432/db         # 短格式
DATABASE_URL=psql://user:pass@host:5432/db       # CLI风格

# JDBC URL（自动转换）
DATABASE_URL=jdbc:postgresql://user:pass@host:5432/db  # 来自Java应用
DATABASE_URL=jdbc:postgres://user:pass@host:5432/db    # 带变体的JDBC

# 显式指定异步驱动
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db

# 带支持的参数（见下方列表）
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：

# 简单URL（自动添加驱动）
DATABASE_URL=mysql://root:password@localhost:3306/mydb

# MariaDB URL（规范化为mysql+aiomysql）
DATABASE_URL=mariadb://user:pass@host:3306/db    # MariaDB风格
DATABASE_URL=maria://user:pass@host:3306/db      # 短格式

# JDBC URL（自动转换）
DATABASE_URL=jdbc:mysql://user:pass@host:3306/db     # 来自Java应用
DATABASE_URL=jdbc:mariadb://user:pass@host:3306/db   # JDBC MariaDB

# 显式指定异步驱动
DATABASE_URL=mysql+aiomysql://user:pass@host:3306/db

# 带字符集（对正确的Unicode支持至关重要）
DATABASE_URL=mariadb://user:pass@remote.host: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：

# 简单URL（自动添加驱动）
DATABASE_URL=clickhouse://default:@localhost:9000/default

# 短格式（规范化为clickhouse+asynch）
DATABASE_URL=ch://user:pass@host:9000/db         # 短格式
DATABASE_URL=click://user:pass@host:9000/db      # 替代格式

# JDBC URL（自动转换）
DATABASE_URL=jdbc:clickhouse://user:pass@host:9000/db  # 来自Java应用
DATABASE_URL=jdbc:ch://user:pass@host:9000/db         # 带短格式的JDBC

# 显式指定异步驱动
DATABASE_URL=clickhouse+asynch://user:pass@host:9000/db

# 带性能设置
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）会被过滤掉，因为它们可能会导致兼容性问题。
  • 仅保留已知与异步驱动兼容的参数。

使用方法

运行服务器

# 运行服务器（在任何地方都能运行，无需配置PATH）
python -m db_connect_mcp

# 使用环境变量
DATABASE_URL="postgresql://user:pass@host:5432/db" python -m db_connect_mcp

⚠️ 重要提示

使用python -m db_connect_mcp，无论Python的Scripts目录是否在系统路径中，命令都能正常工作。

与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 | | --- | --- | --- | --- | | 模式 | ✅ 全面支持 | ✅ 全面支持 | ✅ 全面支持 | | 表 | ✅ 全面支持 | ✅ 全面支持 | ✅ 全面支持 | | 视图 | ✅ 全面支持 | ✅ 全面支持 | ✅ 全面支持 | | 索引 | ✅ 全面支持 | ✅ 全面支持 | ⚠️ 有限支持 | | 外键 | ✅ 全面支持 | ✅ 全面支持 | ❌ 不支持 | | 约束 | ✅ 全面支持 | ✅ 全面支持 | ⚠️ 有限支持 | | 表大小 | ✅ 精确支持 | ✅ 精确支持 | ✅ 精确支持 | | 行数 | ✅ 精确支持 | ✅ 精确支持 | ✅ 精确支持 | | 列统计信息 | ✅ 全面支持 | ✅ 全面支持 | ✅ 全面支持 | | 采样 | ✅ 全面支持 | ✅ 全面支持 | ✅ 全面支持 |

可用工具

list_schemas

列出数据库中的所有模式。

list_tables

列出模式中的所有表及其元数据。

  • 参数：
    • schema（可选）：模式名称（默认："public"）

describe_table

获取表的详细信息。

  • 参数：
    • table_name：表名
    • schema（可选）：模式名称（默认："public"）

analyze_column

对列进行统计和分布分析。

  • 参数：
    • table_name：表名
    • column_name：列名
    • schema（可选）：模式名称（默认："public"）

sample_data

从表中获取数据样本。

  • 参数：
    • table_name：表名
    • schema（可选）：模式名称（默认："public"）
    • limit（可选）：行数（默认：100，最大：1000）

execute_query

执行只读SQL查询。

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

get_table_relationships

获取模式中的外键关系。

  • 参数：
    • schema（可选）：模式名称（默认："public"）

在Claude中的使用示例

配置完成后，你可以在Claude中使用该服务器：

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

🔧 技术细节

安全与保障

  • 设计为只读：服务器在多个层面强制只读访问：
    • 连接字符串参数。
    • 会话级设置。
    • 查询验证。
  • 禁止数据修改：阻止INSERT、UPDATE、DELETE、CREATE、DROP等修改语句。
  • 查询限制：自动限制所有查询，防止过度使用资源。
  • 无敏感操作：禁止访问系统目录或管理功能。

开发

详细的开发设置、测试和贡献指南请参考开发指南。

项目结构

db-connect-mcp/
├── src/
│   └── db_connect_mcp/
│       ├── adapters/         # 特定数据库适配器
│       │   ├── __init__.py
│       │   ├── base.py      # 基础适配器接口
│       │   ├── postgresql.py # PostgreSQL适配器
│       │   ├── mysql.py     # MySQL适配器
│       │   └── clickhouse.py # ClickHouse适配器
│       ├── core/            # 核心功能
│       │   ├── __init__.py
│       │   ├── connection.py # 数据库连接管理
│       │   ├── executor.py  # 查询执行
│       │   ├── inspector.py # 元数据检查
│       │   ├── analyzer.py  # 统计分析
│       │   └── tunnel.py   # SSH隧道管理
│       ├── models/          # 数据模型
│       │   ├── __init__.py
│       │   ├── capabilities.py # 数据库功能
│       │   ├── config.py    # 配置模型
│       │   ├── database.py  # 数据库模型
│       │   ├── query.py     # 查询模型
│       │   ├── statistics.py # 统计模型
│       │   └── table.py     # 表元数据模型
│       ├── __init__.py
│       ├── __main__.py      # 模块入口点
│       └── server.py        # 主MCP服务器实现
├── tests/
│   ├── unit/            # 单元测试（模拟）
│   ├── module/          # 模块测试（单个组件 + 数据库）
│   ├── integration/     # 集成测试（完整栈）
│   └── conftest.py      # 共享夹具
├── .env.example         # 示例环境配置
├── pyproject.toml      # 项目依赖和控制台脚本
└── README.md          # 本文件

架构

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

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

运行测试

# 启动本地测试数据库（带有示例数据的PostgreSQL 17）
cd tests/docker && docker-compose up -d && cd ../..

# 并行运行所有测试（推荐 - 6个工作线程）
uv run pytest -n 6

# 运行特定测试模块
uv run pytest tests/module/test_inspector.py -v -n 6
uv run pytest tests/integration/ -v -n 6

# 停止测试数据库
cd tests/docker && docker-compose down && cd ../..

# 重置数据库（使用新数据重新初始化）
cd tests/docker && docker-compose down -v && docker-compose up -d && cd ../..

本地测试数据库：

  • 带有7个表、超过50K行示例数据的PostgreSQL 17。
  • 通过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参数控制结果集大小。
  • 服务器会自动限制结果，防止内存问题。
  • 对于大型分析，考虑使用更具体的查询。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端