db-mcp-server
Provides credential-isolated access to PostgreSQL databases, allowing execution of read-only and gated write SQL queries through a secure, tunneling-based connection.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
db-mcp-server
A local MCP server that gives an AI coding assistant (e.g. Claude Code) credential-isolated access to your PostgreSQL databases. The assistant sends only SQL and receives only rows — database usernames, passwords, and SSH keys never enter the model's context or the conversation transcript.
Why
Wiring an AI assistant to a database usually means putting connection strings and passwords somewhere the model (and its transcript) can read them. This server keeps that boundary: it owns the encrypted credentials and the SSH tunnels, exposes a small SQL-only tool surface, and defaults to read-only.
Related MCP server: Postgres Scout MCP
How it works
Catalog (
registry.yaml) — non-secret routing. Organized ascustomers → environments → services; each service maps to a database name and asecret_ref(a pointer into the vault — never a credential).Vault (
vault.enc) — AES-256-GCM with a scrypt-derived key. Holds the DB credentials, decrypted into memory once at launch using a passphrase.Tunnel pool — one SSH tunnel per
(customer, environment)viasshtunnel, bound to an ephemeral127.0.0.1port.Executor —
psycopg.run_queryruns in a Postgres READ ONLY transaction (the engine rejects any write);run_write_queryrequiresconfirm=true.
Install
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1 (bash: source .venv/Scripts/activate)
pip install -e ".[dev]"Configure
Configuration comes from environment variables; defaults resolve relative to the project root.
Variable | Purpose | Default |
| Vault passphrase (required to run the server) | — |
| Path to |
|
| Path to |
|
| Directory holding the SSH PEM keys |
|
| Path to |
|
Provision (first-time setup)
Copy the template and fill in real values:
cp bootstrap.example.yaml bootstrap.yamlPut your SSH private keys in
keys/(filenames must match thepem_keyfields in the catalog).Generate the non-secret catalog and the encrypted vault (prompts for the passphrase you'll reuse to run the server):
python -m db_mcp_server.bootstrap --dry-run # preview, writes nothing python -m db_mcp_server.bootstrap # writes registry.yaml + vault.enc python -m db_mcp_server.vault_admin verify # expect {"ok": true}
bootstrap.yaml holds plaintext credentials — it is git-ignored; delete it
or keep it offline once the vault exists.
Command-line tools
Command | Purpose |
| The MCP server (stdio). Launched by the MCP client, not by hand. |
| Manage credentials in the vault: |
| Split |
(Console commands exist after pip install -e .; the python -m db_mcp_server.<module>
form always works.)
Tools exposed to the assistant
list_databases()— the catalog (customers → environments → services); no secrets.run_query(customer, environment, service, sql, max_rows?)— read-only.run_write_query(customer, environment, service, sql, confirm)— gated write.
Domain failures come back as a structured {error_code, message} rather than an
exception, so the assistant can react.
Register with an MCP client
Example .mcp.json (adjust paths). Use ${DB_MCP_PASSPHRASE} so the passphrase
is read from the shell instead of being written into the file:
{
"mcpServers": {
"db": {
"command": "/absolute/path/to/db-mcp-server/.venv/Scripts/python.exe",
"args": ["-m", "db_mcp_server.server"],
"env": {
"DB_MCP_PASSPHRASE": "${DB_MCP_PASSPHRASE}"
}
}
}
}Security notes
vault.enc,keys/,bootstrap.yaml,*.env, and*.pemare git-ignored — never commit them.The vault passphrase is supplied via
DB_MCP_PASSPHRASE(or a prompt) — never stored inregistry.yaml, argv, or logs.db-vaultreads the DB password via a hidden prompt (getpass), never via argv.run_queryis read-only at the Postgres engine level; writes requireconfirm=true.
Tests
pip install -e ".[dev]" && python -m pytest -qThe DB integration test is skipped unless DB_MCP_TEST_DSN points at a reachable
PostgreSQL.
Roadmap (not in this build)
Persistent audit trail, multi-user operation, external secret-manager backing, schema-introspection tools, and a permission denylist to turn the credential isolation into a hard boundary.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query PostgreSQL databases in plain English — LLM-generated, safety-validated SQL.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with PostgreSQL databases using natural language queries, providing secure read-only access to database schemas and SQL translation capabilities.69 npmISC
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to safely explore, analyze, and maintain PostgreSQL databases with read-only mode by default, SQL injection prevention, query performance analysis, and optional write operations.87 npmApache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query PostgreSQL, inspect schemas, and explain queries, designed for local and development databases with read-only safety by default.38 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables an AI assistant to run guarded, read-only SQL queries against a Postgres database with enforced limits and validation.MIT