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

✅ 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