Rheopyrin/db-access-mcp

MCP (Model Context Protocol) stdio server that gives AI agents (Claude Code, Claude
Desktop, any MCP client) access to configured databases:
- **PostgreSQL** (≥ 10)
- **MySQL** (≥ 5; read-only sessions require ≥ 5.6)
- **Amazon Redshift**
- **Microsoft SQL Server** (via tedious)
with **SSH / AWS SSM tunnels**, pluggable **secret providers** (env vars, HashiCorp
Vault, AWS Secrets Manager) and strict **per-instance isolation** — many MCP
instances can run concurrently on one machine without sharing connections or
tunnels, and crashed instances never leave orphaned tunnel processes behind.
Highlights
**Tools:** connection_list / connection_find / connection_test, query,
query_plan (EXPLAIN), query_to_file (streamed CSV/JSONL export that bypasses the
model context), up_tunnel / down_tunnel / tunnel_list, config_reload
(pick up new connections/tunnels without a restart).
**Security-first design:**
- **Verified SSH tunnels** — the bastion host key is checked against a
host_key_sha256 pin or known_hosts, failing closed on mismatch (MITM defence),
not blindly trusted.
- **read_only seatbelt** + single-statement-by-default, which also closes the
SET session read-only off; INSERT … bypass.
- **Confined file exports** — query_to_file writes only under the export dir or an
allow_export_paths root; it cannot clobber ~/.ssh, dotfiles or the config dir.
- **No secrets leak out** — tools never return stacks or credentials; logs redact by
key name *and* scrub inline user:password@host URIs.
- **Pluggable secret providers** — env vars, HashiCorp Vault (dynamic leases with
auto-refresh and atomic pool swaps), AWS Secrets Manager, RDS IAM auth tokens and
temporary Redshift credentials.
**Tunnels & crash-safety:** in-process SSH (dies with the process — no orphaned
ports) and AWS SSM under a watchdog (killed even on SIGKILL), with AWS SSO bootstrap.
Every instance's pools and tunnels are isolated; a crashed instance's tunnels are
reaped by the next start.
Quick start
On first start the server creates the working directory ~/.db_acess_mcp
(intentional spelling — it is the product contract) with an empty config.json, an
empty conf.d/ directory and a full config.example.json covering every dialect,
secret provider and tunnel type. The export directory (default
/tmp/db-access-mcp/exports) is **not** created up front — query_to_file makes it
on demand on the first export. Edit ~/.db_acess_mcp/config.json, restart the MCP
server, done.
Integrating the MCP
The server speaks MCP over **stdio**: any client that can spawn
npx -y @rheopyrin/db-access-mcp (or node /dist/cli.js for a local build) can use it.
Every spawned instance is fully isolated — its own pools, tunnels and idle timers —
so it is safe to register it in several clients/sessions at once.
Claude Code
Check with /mcp inside a session (server status, reconnect). Server stderr logs
land in ~/Library/Caches/claude-cli-nodejs/ /mcp-logs-db-access-mcp/
(macOS). After editing config.json, reconnect the server (/mcp) — the config
is read at startup only.
Or declare it in the project's .mcp.json directly:
Claude Desktop
Add the same mcpServers block to the config file and restart the app:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Cursor / other MCP clients
Any stdio-capable client works with the same shape — command npx,
args ["-y", "@rheopyrin/db-access-mcp"] (Cursor: ~/.cursor/mcp.json, same mcpServers
format). Two things to know:
- **stdout is the protocol** — if your client shows a JSON-RPC parse error, make
sure nothing wraps the command with extra output; all server logs go to stderr.
- Pass CLI options via args, e.g.
["-y", "@rheopyrin/db-access-mcp", "--workdir", "/opt/mcp-db", "--log-level", "warn"].
Local build (development)
Trying it without a client
opens a web UI listing all tools with call forms and live stderr. A sensible
first-session sequence: dialect_list → connection_list →
connection_test on one connection → query.
Requirements on the host
- Node.js ≥ 20.19.
- For **ssm tunnels**: AWS CLI + session-manager-plugin on PATH; for the SSO bootstrap a browser (login opens interactively).
- For **ssh tunnels**: nothing extra (in-process ssh2 client).
CLI options
| Option | Env var | Default |
|---|---|---|
| --workdir (or first positional) | DB_ACCESS_MCP_WORKDIR | ~/.db_acess_mcp |
| --exportdir (or second positional) | DB_ACCESS_MCP_EXPORTDIR | /tmp/db-access-mcp/exports |
| --config | DB_ACCESS_MCP_CONFIG | discovery: /config.json + /conf.d/*.json |