# Claude Multi-Database MCP Server

[English](README.md) | [中文](README_CN.md)

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

```bash
# 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

```bash
# 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:

```json
{
  "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:

```bash
# 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

```bash
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`

```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.

```python
{
  "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.

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

### 3. search_tables

Search tables by keyword across all datasources.

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

### 4. list_datasources

List all available datasources.

```python
{}
```

## 📖 Documentation

- [Installation Guide](docs/installation.md)
- [Configuration Guide](docs/configuration.md)
- [Usage Guide](docs/usage.md)
- [API Reference](docs/api.md)
- [Troubleshooting](docs/troubleshooting.md)

## 🧪 Testing

```bash
# 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](docs/security.md) for details.

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) 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](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Anthropic's Claude](https://www.anthropic.com/claude)
- Uses [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- Database drivers: psycopg2, clickhouse-driver, pyodps

## 📬 Contact

- Issues: [GitHub Issues](https://github.com/yourusername/claude-multi-db-mcp/issues)
- Discussions: [GitHub Discussions](https://github.com/yourusername/claude-multi-db-mcp/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