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:

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

Example 2: View Table Structure

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

Claude will:

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

Example 3: Execute Analysis

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

Claude will:

1. Search for relevant tables
2. Check table structure
3. Generate SQL query
4. 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:

1. Query product list from local_pg
2. Query click and conversion data from clickhouse
3. Join and analyze in memory
4. 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

• Installation Guide
• Configuration Guide
• Usage Guide
• API Reference
• Troubleshooting

🧪 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/

🔒 Security

• ✅ Only read-only database users
• ✅ SQL validation blocks DDL/DML operations
• ✅ Automatic LIMIT enforcement
• ✅ Query logging and audit trail
• ✅ Sensitive data filtered through database views

See Security Best Practices for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide first.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Anthropic's Claude
• Uses Model Context Protocol (MCP)
• Database drivers: psycopg2, clickhouse-driver, pyodps

📬 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

• [ ] Add MySQL support
• [ ] Add MongoDB support
• [ ] Query result visualization
• [ ] Query template library
• [ ] Redis result caching
• [ ] Multi-user permission system
• [ ] Web UI for management

---

Made with ❤️ for the Claude community