Pg Da

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

    

用于跨多个数据库系统进行探索性数据分析的只读MCP（模型上下文协议）服务器。该服务器提供对PostgreSQL、MySQL和ClickHouse数据库的安全、只读访问，并具有全面的分析功能。

演示

db-connect-mcp demo

快速开始

1. 安装：

   pip install db-connect-mcp

1. 添加到克劳德桌面 claude_desktop_config.json:

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

1. 重新启动克劳德桌面 开始查询你的数据库！

备注：使用 python -m db_connect_mcp 确保即使Python的Scripts目录不在PATH中，该命令也能正常工作。

特性

🗄️ 多数据库支持

• 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：

# 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: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：

# 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 -m db_connect_mcp 无论Python的Scripts目录是否在PATH中，它都能正常工作。

使用Claude代码

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

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

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

MySQL通过SSH隧道：

{
  "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_PATH，您可以使用 SSH_PRIVATE_KEY 以将私钥内容直接作为字符串（原始PEM或base64编码的PEM）传递。这在装载密钥文件不切实际的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的工作方式相同。

为了发展：参见 开发指南 用于从紫外线源运行。

数据库功能支持

可用工具

list_schemas

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

list_tables

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

• 参数：

- schema （可选）：架构名称（默认：“public”）

describe_table

获取有关表格的详细信息。

• 参数：

- table_name：表的名称 - schema （可选）：架构名称（默认：“public”）

分析栏

使用统计数据和分布分析列。

• 参数：

- table_name：表的名称 - column_name：列的名称 - schema （可选）：架构名称（默认：“public”）

样本数据

从表中获取数据样本。

• 参数：

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

execute_query

执行只读SQL查询。

• 参数：

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

get_table_关系

获取架构中的外键关系。

• 参数：

- 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/         # 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个表中有50K多行示例数据
• 通过Docker Compose自动初始化
• 无需云数据库或.env配置
• 看 详见

看 开发指南 和 测试指导 详细的测试说明。

故障排除

连接问题

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

数据库特定问题

PostgreSQL：

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

MySQL/MariaDB：

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

ClickHouse：

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

权限错误

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

大型结果集

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

作者

由...创建 桂.

贡献

欢迎投稿！默认情况下，服务器被设计为只读和安全的。任何新功能都应保持这些安全保证。

许可证

MIT许可证-有关详细信息，请参阅许可证文件