# 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](https://github.com/seraved/mcp_core).

## Install

```bash
poetry install
```

## 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

```bash
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

```bash
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
```