MCP 服务器

Claude Multi-Database MCP Server

An MCP server that enables Claude to query multiple databases (PostgreSQL, ClickHouse, MaxCompute) with automatic schema discovery and intelligent table search.

README

Claude Multi-Database MCP Server

English | 中文

A production-ready MCP (Model Context Protocol) server that enables Claude to query multiple heterogeneous databases with automatic schema discovery and intelligent table search.

🌟 Features

🔌 Multi-Database Support: PostgreSQL, ClickHouse, Alibaba Cloud MaxCompute
🔍 Smart Schema Discovery: Automatically fetches table structures and column comments from databases
🔎 Intelligent Search: Cross-database table search based on keywords
🛡️ Security First: SQL validation, read-only access, automatic LIMIT enforcement
⚡ Performance Optimized: Metadata caching, connection pooling
📊 Cross-Source Analysis: Query and analyze data across multiple databases
🎯 Zero Maintenance: No manual schema catalog needed

📋 Prerequisites

Python 3.8+
Access to one or more supported databases
Claude Desktop or Anthropic API access

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/yourusername/claude-multi-db-mcp.git
cd claude-multi-db-mcp

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .

2. Configuration

# Copy configuration template
cp config/database_config.json.example config/database_config.json

# Edit configuration with your database credentials
nano config/database_config.json

Example configuration:

{
  "datasources": {
    "business_pg": {
      "type": "postgresql",
      "host": "your-host.example.com",
      "port": 5432,
      "database": "business_db",
      "user": "readonly_user",
      "password": "your_password"
    }
  }
}

3. Create Read-Only Users

For security, create read-only database users:

# PostgreSQL
psql -h your-host -U admin -d your_db -f scripts/create_readonly_users.sql

# ClickHouse
clickhouse-client --host your-host --multiquery < scripts/create_readonly_users.sql

4. Test Connection

python scripts/test_connection.py

5. Configure Claude Desktop

Edit your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "database-query": {
      "command": "python",
      "args": ["/absolute/path/to/claude-multi-db-mcp/src/mcp_server.py"]
    }
  }
}

Restart Claude Desktop.

💡 Usage Examples

Once configured, you can chat with Claude naturally:

Example 1: Search for Tables

You: "Find tables related to users"

Claude will:

Call search_tables(keyword="users")
Return matching tables from all databases
Show table locations and descriptions

Example 2: View Table Structure

You: "What columns does the users table have in business_pg?"

Claude will:

Call get_table_metadata(source="business_pg", table="users")
Display all columns with names, types, and comments

Example 3: Execute Analysis

You: "Count new users by channel for last month"

Claude will:

Search for relevant tables
Check table structure
Generate SQL query
Execute and analyze results

Example 4: Cross-Database Analysis

You: "Compare product data in local_pg with click data in clickhouse to find products with high views but low conversion"

Claude will:

Query product list from local_pg
Query click and conversion data from clickhouse
Join and analyze in memory
Provide insights and recommendations

🛠️ Available MCP Tools

1. query_database

Execute SQL queries on specified datasource.

{
  "source": "business_pg",
  "sql": "SELECT * FROM users WHERE created_at > '2024-01-01' LIMIT 10"
}

2. get_table_metadata

Get table structure and column comments.

{
  "source": "business_pg",
  "table_name": "users"  # Optional, omit to list all tables
}

3. search_tables

Search tables by keyword across all datasources.

{
  "keyword": "order",
  "sources": ["business_pg", "clickhouse"]  # Optional
}

4. list_datasources

List all available datasources.

{}

📖 Documentation

🧪 Testing

# Run all tests
python -m pytest tests/

# Run specific test
python -m pytest tests/test_query_tool.py

# Test with coverage
python -m pytest --cov=src tests/