Db Connect MCP

🚀 db-connect-mcp - 多數據庫MCP服務器

db-connect-mcp是一個只讀的MCP（模型上下文協議）服務器，專為跨多個數據庫系統進行探索性數據分析而設計。該服務器可安全、只讀地訪問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目錄不在系統路徑中，該命令依然可以正常工作。

✨ 主要特性

🗄️ 多數據庫支持

• 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從源代碼運行。

數據庫特性支持

可用工具

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文件。