Db Access MCP

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

// Claude Code / Claude Desktop MCP config

{ "mcpServers": { "db-access-mcp": { "command": "npx", "args": ["-y", "@rheopyrin/db-access-mcp"] } } }

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

# current project only (writes .mcp.json in the project root)

claude mcp add db-access-mcp -- npx -y @rheopyrin/db-access-mcp

for all your projects

claude mcp add --scope user db-access-mcp -- npx -y @rheopyrin/db-access-mcp

with options (custom config dir, verbose logs, extra env file)

claude mcp add db-access-mcp -- npx -y @rheopyrin/db-access-mcp --workdir ~/.db_acess_mcp --log-level debug --env-file ~/.db_acess_mcp/secrets.env

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:

{

"mcpServers": { "db-access-mcp": { "command": "npx", "args": ["-y", "@rheopyrin/db-access-mcp"] } } }

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)

git clone <repo> && cd db_access_mcp && npm ci && npm run build

claude mcp add db-access-mcp-dev -- node /abs/path/db_access_mcp/dist/cli.js --log-level debug

Trying it without a client

npx -y @modelcontextprotocol/inspector npx -y @rheopyrin/db-access-mcp

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

db-access-mcp [workdir] [exportdir] [--workdir <dir>] [--exportdir <dir>] [--config <file>] [--env-file <file>]... [--log-level <level>]

The workdir holds config.json, conf.d/, config.example.json and the runtime instances/ and sso/ state (unchanged from earlier releases). The exportdir is where query_to_file writes exports (created on demand, not at startup); allow_export_paths adds extra writable roots.

All logs are JSON lines on stderr (stdout belongs to the MCP protocol). Values of keys matching password, token, secret, privateKey etc. are redacted.

MCP tools

config_reload

Edit config.json / conf.d/*.json (or the --config file), call config_reload, and the next connection_list, query, up_tunnel, … sees the new definitions. The files are re-read, re-validated (schema + semantics + dialect check) and the config env_files are re-applied before anything is swapped in — an invalid config changes nothing: the server keeps running on the previous configuration and the tool returns the validation error.

The reload is deliberately non-disruptive: open pools and running tunnels are never closed, drained, recreated or reconfigured, even when their definition changed or was removed from the file. They keep the definition they were created with until they are closed the normal way (idle timeout, down_tunnel, server exit); the next pool/tunnel created after that uses the new definition. Every such case is listed in the response's warnings.

Response: files (what was read), connections and tunnels as {added, removed, changed, unchanged}, the pool_defaults_changed / limits_changed / env_files_changed flags, and warnings. Per-call and per-connection limits are read at call time, so they take effect immediately; pool settings only apply to pools created after the reload.

Security note for query_to_file: writes are confined to the export dir (default /tmp/db-access-mcp/exports) plus any roots listed in allow_export_paths (e.g. ["/tmp", "~/data_files"]) — every subpath below a listed root is allowed, anything else is rejected, so the tool cannot clobber ~/.ssh, dotfiles or the workdir. It only ever creates files (no reads, no appends) and refuses to overwrite without an explicit overwrite: true. Cells are written verbatim; be mindful of CSV-injection when opening exports in Excel.

Configuratio