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 <path>/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/<project-slug>/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