mcp_db

MCP server for running SQL against PostgreSQL and ClickHouse (HTTP interface) connections, with per-connection allow/deny policy by statement group (DDL/DML/DQL/DCL/TCL).

Built on mcp_core.

Install

poetry install

Related MCP server: Multi-DB MCP Server

Configure

Copy db_connections.example.yaml to db_connections.yaml, edit connections. Secrets are env-var references only (user_env/password_env) — export the actual values before starting the server.

Run

export MCP_DB_CONFIG=/path/to/db_connections.yaml
export PG_USER=... PG_PASSWORD=...
export CH_USER=... CH_PASSWORD=...
poetry run mcp-db

Tools

• db_query(connection, sql) — DQL only, rows truncated at max_rows.

• db_execute(connection, sql) — DDL/DML/DCL/TCL, returns rowcount.

• db_list_connections() — lists configured connection names, drivers, and policy modes.

Policy modes (per connection, mode field)

• readonly (default) — only DQL allowed.

• restricted — only groups listed in allow_groups allowed; empty allow_groups denies everything.

• unrestricted — everything allowed except groups listed in deny_groups.

Tests

poetry run pytest -m "not integration"                       # fast unit tests
docker compose -f docker-compose-test.yml up -d               # postgres + clickhouse test containers
poetry run pytest                                              # full suite
docker compose -f docker-compose-test.yml down