Common Database

You run a single MCP server that provides safe, read-only access to multiple databases through common drivers. It lets Claude Code, Claude Desktop, and Windsurf IDE explore schemas, inspect tables, and run parameterized queries without risking data modification.

How to use

Start the MCP server and connect your MCP client to it. You will be able to list configured databases, inspect schemas, view tables, and execute read-only queries using parameterized inputs for safety. Use the provided MCP prompts to guide you through exploring a database and analyzing table structures.

How to install

Prerequisites: install Python 3.9 or higher and ensure you have pip available.

cd /path/to/jdbc-mcp-server
pip install -e .

Optional development and testing dependencies can be installed with.

pip install -e ".[dev]"

Install database drivers automatically as part of startup; you will need Python and the corresponding drivers on first run. Supported drivers include PostgreSQL (psycopg2-binary), MySQL (mysql-connector-python), and SQLite (sqlite3 is built into Python). For DB2 iSeries on macOS, install the IBM DB2 driver.

pip install --no-cache-dir ibm_db

Configuration and startup details

Configure the MCP server to run as a stdio (local) server using Python and the module path.

{
  "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"
      }
    }
  }
}

Security best practices

Operate in read-only mode by default when exploring production databases to prevent unintended data changes. Create dedicated database users with SELECT-only permissions for your MCP workflows. Store credentials in environment variables rather than hard-coding them. Use SSL/TLS for database connections, restrict access by IP, and prefer SSH tunnels for remote databases.

Troubleshooting

If you encounter a connection issue, verify the database server is running and that the hostname and port are correct. Check firewall rules and try a direct database client connection to rule out network problems.

If authentication fails, confirm the credentials and permissions of the configured user. For PostgreSQL, ensure the connection method allows your host and user in pg_hba.conf.

Development

Run tests with the project’s test suite and enable debug logging during development to observe MCP server activity.

pytest tests/

export LOG_LEVEL=DEBUG
python -m jdbc_mcp_server

Available tools

list_databases

List all configured database connections.

test_connection

Test connectivity to a specific database.

list_schemas

List all schemas for a database (PostgreSQL/MySQL).

list_tables

List all tables within a schema (or database if applicable).

describe_table

Get detailed information about a table’s columns and keys.

execute_query

Execute a SELECT query with parameterized inputs and optional limit.

get_sample_data

Fetch a small sample of rows from a table.