DB Conn MCP server

<!-- mcp-name: io.github.Idle-Sync/db-conn-mcp -->

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 Dialect seam, so adding MySQL/SQLite later is a single new file.

Why

• Read stays read. A read database runs every query in a native read-only transaction, and the read tool only accepts a single read-only statement (SELECT/WITH/VALUES/TABLE/SHOW/EXPLAIN) — so an agent can't slip in a write or a SET … READ WRITE to flip the session. For a hard, privilege-level guarantee that holds no matter what, point the DSN at a read-only database role (see Use a read-only role).
• No secret leaks. DSNs/passwords are never logged or returned by any tool. Connection failures come back as sanitized diagnostics (a category + fix), never a raw traceback with your host and credentials in it.
• Tiered write safety. Writes are gated server-side: mode (hard, native) → dry-run first (a commit is refused unless that exact statement was previewed) → yolo (per-database trust) → user_consent (explicit per-operation approval).
• Zero-friction setup. An interactive wizard registers your database and injects the server into your AI client's config for you — across 9 popular clients, each in its own format. Prefer clicking? db-conn-mcp gui opens a local dashboard that does the same, and proves each client can actually launch the server.

Install

Requires Python 3.12+.

# Recommended: isolated but globally available on your PATH
pipx install db-conn-mcp

# or plain pip
pip install db-conn-mcp

This installs the db-conn-mcp command.

Upgrade

Not sure how you installed it? Each manager keeps its own registry — ask them:

pipx list                 # db-conn-mcp listed here → pipx
uv tool list              # listed here → uv tool
pip show db-conn-mcp      # found in the current Python env → pip

If none of those know it, your MCP client config is likely launching it via uvx (check the command in the client's config entry — that entry is the source of truth for what actually runs, and which db-conn-mcp / Get-Command db-conn-mcp shows the binary on your PATH).

Then use the matching upgrade command:

pipx upgrade db-conn-mcp          # pipx
pip install --upgrade db-conn-mcp # pip
uv tool upgrade db-conn-mcp       # uv tool

Running via uvx (e.g. in an MCP client config)? There's nothing installed to upgrade, but uvx caches resolved versions — use db-conn-mcp@latest as the command to always resolve the newest release, or run uv cache clean db-conn-mcp to force a re-resolve.

After upgrading, restart/reconnect your AI client so it picks up the new version (and any new tools). Verify with db-conn-mcp -v.

You don't have to remember to check. When you run a db-conn-mcp subcommand in a terminal, it prints a single line if a newer release is published — looked up in the background, so it never slows a command down or changes its exit code (offline just means no line). Set DBCONNMCPNOUPDATE_CHECK=1 to silence it. The server your MCP client launches never checks; db-conn-mcp doctor is the deliberate, authoritative version of the same question.

Shortened. The full README is on GitHub.