db-connect-mcp - Multi-Database MCP Server

A read-only MCP (Model Context Protocol) server for exploratory data analysis across multiple database systems. This server provides safe, read-only access to PostgreSQL, MySQL, and ClickHouse databases with comprehensive analysis capabilities.

Demo

Quick Start

1. Install:

   Terminal

   Copy

   pip install db-connect-mcp
   

2. Add to Claude Desktop claude_desktop_config.json:

   config.json

   Copy

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

3. Restart Claude Desktop and start querying your database!

Note: Using python -m db_connect_mcp ensures the command works even if Python's Scripts directory isn't in your PATH.

Features

🗄️ Multi-Database Support

• PostgreSQL - Full support with advanced metadata and statistics
• MySQL - Complete support for MySQL and MariaDB databases
• ClickHouse - Support for analytical workloads and columnar storage

🔍 Database Exploration

• List schemas - View all schemas in the database
• List tables - See all tables with metadata (size, row counts, comments)
• Describe tables - Get detailed column information, indexes, and constraints
• View relationships - Understand foreign key relationships between tables

📊 Data Analysis

• Column profiling - Statistical analysis of column data
  • Basic statistics (count, unique values, nulls)
  • Numeric statistics (mean, median, std dev, quartiles)
  • Value frequency distribution
  • Cardinality analysis
• Data sampling - Preview table data with configurable limits
• Custom queries - Execute read-only SQL queries safely
• Object search - Find schemas, tables, views, columns, and indexes without loading the full catalog
• Query plans - Inspect estimated plans or opt into EXPLAIN ANALYZE where supported

🔒 Safety Features

• Read-only enforcement - All connections are read-only at multiple levels
• Query validation - Only SELECT and WITH queries are allowed
• Automatic limits - Queries are automatically limited to prevent large result sets
• Connection string safety - Automatically adds read-only parameters
• Database-specific safety - Each adapter implements appropriate safety measures

🔭 Observability

db-connect-mcp inherits the MCP SDK's built-in OpenTelemetry server instrumentation. The API is a no-op until the launching process configures an SDK and exporter. Review exporter sampling and redaction before production use, because database identifiers and error details may be sensitive.

💡 Best Practices

Tip: db-connect-mcp works best with databases that have proper comments on tables and columns. When your database includes descriptive comments, the MCP server can provide richer context to AI assistants, leading to better understanding of your data model and more accurate query suggestions.

Adding comments in 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';

Adding comments in 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';

The server automatically retrieves and displays these comments when describing tables, helping AI assistants understand the purpose and semantics of your data.

🔐 SSH Tunnel Support

• Secure remote access - Connect to databases behind firewalls via SSH tunnels
• Automatic tunnel management - Tunnel lifecycle handled transparently (start, health check, restart, cleanup)
• Reliable native forwarding - Paramiko SSHClient transport with target preflight and stable-port recovery
• Flexible authentication - Password or private key based SSH authentication
• Any database type - Works with PostgreSQL, MySQL, and ClickHouse through the same tunnel

See the SSH Tunnel Guide for configuration details.

Installation

Prerequisites

• Python 3.10 or higher
• A database: PostgreSQL (9.6+), MySQL/MariaDB (5.7+/10.2+), or ClickHouse

Install via pip

pip install db-connect-mcp

That's it! The package is now ready to use.

For developers: See Development Guide for setting up a development environment.

Configuration

Create a .env file with your database connection string:

DATABASE_URL=your_database_connection_string_here

The server automatically detects the database type and adds appropriate read-only parameters.

Connection String Examples

The server now provides more flexible and secure URL handling:

• Automatic driver detection: Async drivers are automatically added if not specified
• JDBC URL support: JDBC prefixes are automatically handled
  • jdbc:postgresql://... → postgresql+asyncpg://...
  • jdbc:mysql://... → mysql+aiomysql://...
  • Works with all dialect variations (e.g., jdbc:postgres://, jdbc:mariadb://)
• Database dialect variations: Common variations are automatically normalized
  • PostgreSQL: postgresql, postgres, pg, psql, pgsql
  • MySQL/MariaDB: mysql, mariadb, maria
  • ClickHouse: clickhouse, ch, click
• Allowlist-based parameter filtering: Only known-safe parameters are preserved
• Database-specific parameters: Each database type has its own set of supported parameters
• Robust parsing: Handles various URL formats gracefully

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

Supported PostgreSQL Parameters:

• application_name - Identifies your app in pg_stat_activity (useful for monitoring)
• connect_timeout - Connection timeout in seconds
• command_timeout - Default timeout for operations
• ssl / sslmode - SSL connection requirements (automatically converted for asyncpg compatibility)
• server_settings - Server settings dictionary
• options - Command-line options to send to server
• Performance tuning: prepared_statement_cache_size, max_cached_statement_lifetime, etc.

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

Supported MySQL Parameters:

• charset - Character encoding (e.g., utf8mb4) - critical for data integrity
• use_unicode - Enable Unicode support
• connect_timeout, read_timeout, write_timeout - Various timeouts
• autocommit - Transaction autocommit mode
• init_command - Initial SQL command to run
• sql_mode - SQL mode settings
• time_zone - Time zone setting

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

Supported ClickHouse Parameters: