Common Database MCP Server

A Model Context Protocol (MCP) server that provides database connectivity to Claude Code, Claude Desktop, and Windsurf IDE. Supports PostgreSQL, MySQL, SQLite, and DB2 iSeries databases through native Python drivers.

Features

✅ Multiple Database Support: PostgreSQL, MySQL, SQLite, DB2 iSeries
✅ Read-Only by Default: Safe database exploration without risk of data modification
✅ Connection Pooling: Efficient connection management for network databases
✅ SQL Injection Prevention: Parameterized queries and query validation
✅ Cross-Platform: Works on macOS, Linux, and Windows
✅ MCP Tools: Execute queries, inspect schemas, explore tables
✅ MCP Resources: Database schemas as resources
✅ MCP Prompts: Guided workflows for database exploration

Installation

Prerequisites

Python 3.9 or higher
pip

Install from Source

cd /Users/dave/claude-projects/jdbc-mcp-server pip install -e .

Install Optional Dependencies

For development and testing:

pip install -e ".[dev]"

Database Driver Installation

The server automatically installs drivers for:

PostgreSQL (psycopg2-binary)
MySQL (mysql-connector-python)
SQLite (sqlite3 - built into Python)

For DB2 iSeries on macOS:

# DB2 driver installation pip install --no-cache-dir ibm_db

Note: ibm_db works on macOS (both Intel and Apple Silicon M1/M2/M3).

Configuration

Claude Code Configuration

Add the server to your ~/.claude/mcp.json or Claude Desktop configuration:

{ "mcpServers": { "database": { "command": "python", "args": ["-m", "jdbc_mcp_server"], "env": { "DB_POSTGRES_TYPE": "postgresql", "DB_POSTGRES_HOST": "localhost", "DB_POSTGRES_PORT": "5432", "DB_POSTGRES_DATABASE": "myapp", "DB_POSTGRES_USERNAME": "readonly_user", "DB_POSTGRES_PASSWORD": "secure_password", "DB_POSTGRES_READ_ONLY": "true", "DB_POSTGRES_POOL_SIZE": "10" } } } }

Environment Variables

Configure databases using environment variables with the format:

DB_<NAME>_TYPE=postgresql|mysql|sqlite|db2 DB_<NAME>_HOST=hostname DB_<NAME>_PORT=port DB_<NAME>_DATABASE=database_name DB_<NAME>_USERNAME=username DB_<NAME>_PASSWORD=password DB_<NAME>_READ_ONLY=true|false DB_<NAME>_POOL_SIZE=5

Or use connection strings:

DB_<NAME>_TYPE=postgresql DB_<NAME>_CONNECTION_STRING=postgresql://user:pass@localhost:5432/database

Multiple Database Example

Configure multiple databases:

{ "mcpServers": { "database": { "command": "python", "args": ["-m", "jdbc_mcp_server"], "env": { "DB_PROD_TYPE": "postgresql", "DB_PROD_CONNECTION_STRING": "postgresql://readonly@prod-server:5432/production", "DB_PROD_READ_ONLY": "true", "DB_LOCAL_TYPE": "sqlite", "DB_LOCAL_PATH": "/Users/dave/data/local.db", "DB_LOCAL_READ_ONLY": "false", "DB_ANALYTICS_TYPE": "mysql", "DB_ANALYTICS_HOST": "analytics.example.com", "DB_ANALYTICS_PORT": "3306", "DB_ANALYTICS_DATABASE": "analytics", "DB_ANALYTICS_USERNAME": "analyst", "DB_ANALYTICS_PASSWORD": "password" } } } }

Usage

Available MCP Tools

`list_databases()`

List all configured database connections.

list_databases() # Returns: {"success": True, "databases": [{"name": "prod", "type": "postgresql", "read_only": True}, ...]}

`test_connection(database)`

Test database connectivity.

test_connection(database="prod") # Returns: {"success": True, "connected": True, "database_type": "PostgreSQL", "version": "15.2", ...}

`list_schemas(database)`

List all schemas/databases (PostgreSQL/MySQL only).

list_schemas(database="prod") # Returns: {"success": True, "schemas": ["public", "app", ...]}

`list_tables(database, schema=None)`

List all tables in a database.

list_tables(database="prod", schema="public") # Returns: {"success": True, "tables": ["users", "orders", ...]}

`describe_table(database, table, schema=None)`

Get detailed table schema.

describe_table(database="prod", table="users", schema="public") # Returns: {"success": True, "columns": [{"name": "id", "type": "integer", "nullable": False, "primary_key": True}, ...]}

`execute_query(database, query, parameters=None, limit=100)`

Execute a SELECT query with parameterized inputs.

execute_query( database="prod", query="SELECT * FROM users WHERE status = %s AND created_at > %s", parameters=["active", "2024-01-01"], limit=50 ) # Returns: {"success": True, "columns": [...], "rows": [...], "row_count": 50}

`get_sample_data(database, table, schema=None, limit=10)`

Get sample rows from a table.

get_sample_data(database="prod", table="users", limit=5) # Returns: {"success": True, "columns": [...], "rows": [...]}

Available MCP Resources

`db://{database}/schema`

Get complete database schema as markdown.

`db://{database}/tables/{table}/schema`

Get specific table schema as markdown.

Available MCP Prompts

`explore_database`

Guided workflow for database exploration.

`query_with_safety`

Instructions for generating safe parameterized queries.

`analyze_table_structure`

Analyze table structure and identify relationships.

Security Best Practices

1. Use Read-Only Mode

Always use read-only mode (default) when exploring production databases:

DB_PROD_READ_ONLY=true

2. Create Dedicated Database Users

Create database users with SELECT-only permissions:

PostgreSQL:

CREATE USER readonly_user WITH PASSWORD 'secure_password'; GRANT CONNECT ON DATABASE myapp TO readonly_user; GRANT USAGE ON SCHEMA public TO readonly_user; GRANT SELECT ON ALL TABLES IN SCHEMA public TO readonly_user; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO readonly_user;

MySQL:

CREATE USER 'readonly_user'@'%' IDENTIFIED BY 'secure_password'; GRANT SELECT ON myapp.* TO 'readonly_user'@'%'; FLUSH PRIVILEGES;

3. Use Environment Variables

Store credentials in environment variables, never in code:

export DB_PROD_PASSWORD="$(cat ~/.secrets/db_password)"

4. Network Security

Use SSL/TLS for database connections
Restrict database access by IP address
Use SSH tunnels for remote databases

Troubleshooting

Connection Refused

PostgreSQL/MySQL:

Error: Cannot connect to server. Check if the server is running.

Solutions:

Verify the database server is running
Check hostname and port are correct
Ensure firewall allows connections
Test with psql or mysql command-line tools

Authentication Failed

Error: Invalid username or password

Solutions:

Verify credentials are correct
Check user has necessary permissions
For PostgreSQL, check pg_hba.conf allows connections

SQLite Database Locked

Error: SQLite database is locked by another process.

Solutions:

Close other applications using the database
Wait a moment and try again
Check file permissions

ibm_db Installation Issues (macOS)

If ibm_db fails to install:

# Try with no cache pip install --no-cache-dir ibm_db # For Apple Silicon, ensure using Python 3.9+ python3 --version

Development

Running Tests

pytest tests/

Running with Debug Logging

export LOG_LEVEL=DEBUG python -m jdbc_mcp_server

Project Structure

jdbc-mcp-server/ ├── src/jdbc_mcp_server/ │ ├── __init__.py # Package initialization │ ├── __main__.py # Entry point │ ├── server.py # FastMCP server and tools │ ├── config.py # Configuration management │ ├── errors.py # Exception hierarchy │ ├── utils.py # Utility functions │ └── database/ │ ├── base.py # Abstract database adapter │ ├── postgresql.py # PostgreSQL adapter │ ├── mysql.py # MySQL adapter │ ├── sqlite.py # SQLite adapter │ └── db2.py # DB2 adapter └── tests/ # Test suite

MVP Status

Currently Supported (v0.1.0)

✅ PostgreSQL
✅ MySQL
✅ SQLite
✅ DB2 iSeries
✅ Read-only queries
✅ Connection pooling
✅ Schema inspection
✅ Parameterized queries
✅ MCP tools, resources, and prompts

Coming Soon

🔜 Write operations (opt-in)
🔜 Transaction support
🔜 Query caching
🔜 Stored procedure execution

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues, questions, or contributions:

GitHub Issues: Create an issue
Documentation: This README

Acknowledgments

Built with FastMCP
Implements the Model Context Protocol
Database drivers: psycopg2, mysql-connector-python, ibm_db

Common Database MCP Server

Features

Installation

Prerequisites

Install from Source

Install Optional Dependencies

Database Driver Installation

Configuration

Claude Code Configuration

Environment Variables

Multiple Database Example

Usage

Available MCP Tools

list_databases()

test_connection(database)

list_schemas(database)

list_tables(database, schema=None)

describe_table(database, table, schema=None)

execute_query(database, query, parameters=None, limit=100)

get_sample_data(database, table, schema=None, limit=10)

Available MCP Resources

db://{database}/schema

db://{database}/tables/{table}/schema

Available MCP Prompts

explore_database

query_with_safety

analyze_table_structure

Security Best Practices

1. Use Read-Only Mode

2. Create Dedicated Database Users

3. Use Environment Variables

4. Network Security

Troubleshooting

Connection Refused

Authentication Failed

SQLite Database Locked

ibm_db Installation Issues (macOS)

Development

Running Tests

Running with Debug Logging

Project Structure

MVP Status

Currently Supported (v0.1.0)

Coming Soon

Contributing

License

Support

Acknowledgments

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

`list_databases()`

`test_connection(database)`

`list_schemas(database)`

`list_tables(database, schema=None)`

`describe_table(database, table, schema=None)`

`execute_query(database, query, parameters=None, limit=100)`

`get_sample_data(database, table, schema=None, limit=10)`

`db://{database}/schema`

`db://{database}/tables/{table}/schema`

`explore_database`

`query_with_safety`

`analyze_table_structure`