Db Conn Mcp
A self-hosted MCP server that wires AI agents directly to PostgreSQL databases with a clear security model. It exposes 10 tools for schema inspection, fuzzy column search, value lookup across tables, and read/write queries. Reads run in native read-only transactions and only accept SELECT-style statements. Writes gate through three layers: a hard mode flag, an optional yolo bypass, and explicit user consent with schema preview. The setup wizard registers connections in a local JSON file and auto-injects the server config into Claude Desktop, Cursor, Windsurf, VS Code, and others. Useful when you want an agent to explore or mutate a database without building custom tooling, and you trust read-only roles or the tiered write gates enough to point it at real data.
- GitHub stars
- 2
- tools
- 23
- transport
- STDIO
- last updated
- Nov 12, 2026
Tools
23 toolsPublic tool metadata for what this MCP can expose to an agent.
list_databasesConfigured databases (name, mode, yolo, and `active_port` when a fallback port is in use — no DSN).
Configured databases (name, mode, yolo, and `active_port` when a fallback port is in use — no DSN).
No parameter schema in public metadata yet.
list_tablesTables and views in a database. Narrow it in the database rather than after the fact: `pattern` keeps only names containing it (fuzzy, case-insensitive) and `limit` caps the number of rows.
Tables and views in a database. Narrow it in the database rather than after the fact: `pattern` keeps only names containing it (fuzzy, case-insensitive) and `limit` caps the number of rows.
No parameter schema in public metadata yet.
get_table_schemaColumns, types, primary/foreign keys for a table. Pass `include_indexes=true` to also get its indexes (`name`, key `columns` in index order — an INCLUDE payload is not listed — `unique`, `method`); omitted by default.
Columns, types, primary/foreign keys for a table. Pass `include_indexes=true` to also get its indexes (`name`, key `columns` in index order — an INCLUDE payload is not listed — `unique`, `method`); omitted by default.
No parameter schema in public metadata yet.
get_database_schemaThe whole database's schema in one deterministic call. `format="json"` (default) returns every table's columns/types/PK/FK; `format="sql"` returns a self-contained, runnable DDL script (tables, sequences, PK/FK/UNIQUE/CHECK, indexes, trigger functions, triggers) — no extra too...
The whole database's schema in one deterministic call. `format="json"` (default) returns every table's columns/types/PK/FK; `format="sql"` returns a self-contained, runnable DDL script (tables, sequences, PK/FK/UNIQUE/CHECK, indexes, trigger functions, triggers) — no extra too...
No parameter schema in public metadata yet.
dump_schema_faithfulByte-faithful schema dump via the database's own `pg_dump --schema-only` — the most complete/runnable export. Requires the `pg_dump` binary on the server host; if missing, returns `pg_dump_not_found` with install guidance.
Byte-faithful schema dump via the database's own `pg_dump --schema-only` — the most complete/runnable export. Requires the `pg_dump` binary on the server host; if missing, returns `pg_dump_not_found` with install guidance.
No parameter schema in public metadata yet.
sample_table_rowsFirst N rows of a table (default 10). Values render as on `execute_read_query`: bytea as `\x` hex text, a `"char"` column as its character.
First N rows of a table (default 10). Values render as on `execute_read_query`: bytea as `\x` hex text, a `"char"` column as its character.
No parameter schema in public metadata yet.
find_columnsFind columns by name across all tables (fuzzy, case-insensitive). `limit` caps the number of rows for a broad pattern.
Find columns by name across all tables (fuzzy, case-insensitive). `limit` caps the number of rows for a broad pattern.
No parameter schema in public metadata yet.
search_valueFind where a value appears across tables (fuzzy); returns table/column hits + samples. Pass `tables=[…]` to scope it.
Find where a value appears across tables (fuzzy); returns table/column hits + samples. Pass `tables=[…]` to scope it.
No parameter schema in public metadata yet.
get_object_definitionFaithful SQL definition of a view / function / trigger / sequence / index by name (native `pg_get_*def`; overloads and all schemas returned).
Faithful SQL definition of a view / function / trigger / sequence / index by name (native `pg_get_*def`; overloads and all schemas returned).
No parameter schema in public metadata yet.
execute_read_queryRun a single read-only statement (SELECT/WITH/…) inside a read-only transaction. Optional `params` (real bind parameters via `$1`/`$2`) and `timeout_ms`.
Run a single read-only statement (SELECT/WITH/…) inside a read-only transaction. Optional `params` (real bind parameters via `$1`/`$2`) and `timeout_ms`.
No parameter schema in public metadata yet.
execute_write_queryRun a mutation — gated by the safety model above. Defaults to `dry_run=true`: execute in a transaction, report would-be `rows_affected` or the `RETURNING` rows, always ROLL BACK. Committing (`dry_run=false`) requires a prior preview of the identical statement. Also takes `para...
Run a mutation — gated by the safety model above. Defaults to `dry_run=true`: execute in a transaction, report would-be `rows_affected` or the `RETURNING` rows, always ROLL BACK. Committing (`dry_run=false`) requires a prior preview of the identical statement. Also takes `para...
No parameter schema in public metadata yet.
explain_queryEXPLAIN (optionally ANALYZE) a validated read-only query — confirm index usage without any write access. Takes the same `params` as `execute_read_query`.
EXPLAIN (optionally ANALYZE) a validated read-only query — confirm index usage without any write access. Takes the same `params` as `execute_read_query`.
No parameter schema in public metadata yet.
cancel_queryCancel the statement in a given backend `pid` (native `pg_cancel_backend`); the session survives. Find pids via `show_activity`.
Cancel the statement in a given backend `pid` (native `pg_cancel_backend`); the session survives. Find pids via `show_activity`.
No parameter schema in public metadata yet.
open_query_cursorOpen a server-side cursor over a read-only query for large result sets; returns a `cursor_id`. Max 5 open; 15-min idle auto-reap.
Open a server-side cursor over a read-only query for large result sets; returns a `cursor_id`. Max 5 open; 15-min idle auto-reap.
No parameter schema in public metadata yet.
fetch_rowsFetch the next N rows from an open cursor; auto-closes when drained or when the read fails.
Fetch the next N rows from an open cursor; auto-closes when drained or when the read fails.
No parameter schema in public metadata yet.
close_cursorClose a cursor and release its connection (idempotent).
Close a cursor and release its connection (idempotent).
No parameter schema in public metadata yet.
diff_schemasStructural schema diff between two configured databases (tables, columns, types, defaults, PK/FK) — verify a migrated copy matches its source.
Structural schema diff between two configured databases (tables, columns, types, defaults, PK/FK) — verify a migrated copy matches its source.
No parameter schema in public metadata yet.
check_sequencesFind sequences behind their column's max value (the silent post-migration breakage); fix with `setval()`. Lists only the problem sequences by default, with `total_sequences` saying how many were checked; pass `behind_only=false` for the full census.
Find sequences behind their column's max value (the silent post-migration breakage); fix with `setval()`. Lists only the problem sequences by default, with `total_sequences` saying how many were checked; pass `behind_only=false` for the full census.
No parameter schema in public metadata yet.
table_statsApproximate row counts + disk/index sizes per table, largest first (statistics only, no scans).
Approximate row counts + disk/index sizes per table, largest first (statistics only, no scans).
No parameter schema in public metadata yet.
show_activitySanitized pg_stat_activity: pid, state, wait events, query age — no user names, client addresses, or query text (text is opt-in and truncated).
Sanitized pg_stat_activity: pid, state, wait events, query age — no user names, client addresses, or query text (text is opt-in and truncated).
No parameter schema in public metadata yet.
set_yolo_modeEnable/disable `yolo` for one database (persisted).
Enable/disable `yolo` for one database (persisted).
No parameter schema in public metadata yet.
check_databaseTest one database (or all) → OK or a sanitized diagnostic; reports `active_port` when a fallback port answered, and `failed_port` on an UNREACHABLE row when applicable.
Test one database (or all) → OK or a sanitized diagnostic; reports `active_port` when a fallback port answered, and `failed_port` on an UNREACHABLE row when applicable.
No parameter schema in public metadata yet.
doctorDiagnose the whole setup: stale running server processes, a newer PyPI release, connections.json key typos/wrong types, secrets exposure, MCP client entries pointing at dead paths, and per-database connectivity. Returns {check, status, detail, suggested_action} rows; `offline=...
Diagnose the whole setup: stale running server processes, a newer PyPI release, connections.json key typos/wrong types, secrets exposure, MCP client entries pointing at dead paths, and per-database connectivity. Returns {check, status, detail, suggested_action} rows; `offline=...
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageReadme
db-conn-mcp
A dead-simple, self-hosted Model Context Protocol (MCP) server for querying your databases with AI agents (Claude, Cursor, Windsurf, VS Code, Zed, Codex, and more).
It does one thing well: let an agent safely explore and query a database you point it at — with security delegated to the simplest possible primitives (a static JSON file and your database's own read-only transactions), not custom auth servers or fragile SQL parsing.
v1 ships PostgreSQL only. All database-specific code lives behind a
Dialectseam, so adding MySQL/SQLite later is a single new file.
Why
Details
- Repository
- github.com/idle-sync/db-conn-mcp
- Package
db-conn-mcp- Transport
- STDIO
- Registry
- MCP registry, active