db-access-mcp

# db-access-mcp

[![npm](https://img.shields.io/npm/v/@rheopyrin/db-access-mcp?logo=npm)](https://www.npmjs.com/package/@rheopyrin/db-access-mcp)
[![npm downloads](https://img.shields.io/npm/dm/@rheopyrin/db-access-mcp)](https://www.npmjs.com/package/@rheopyrin/db-access-mcp)
[![license: MIT](https://img.shields.io/npm/l/@rheopyrin/db-access-mcp)](LICENSE)
[![node](https://img.shields.io/node/v/@rheopyrin/db-access-mcp)](package.json)

[![db-access-mcp MCP server](https://glama.ai/mcp/servers/Rheopyrin/db-access-mcp/badges/card.svg)](https://glama.ai/mcp/servers/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](https://github.com/tediousjs/node-mssql))

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

```jsonc
// 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

```bash
# 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:

```json
{
  "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)

```bash
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

```bash
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](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) 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>]
```

| 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: `<workdir>/config.json` + `<workdir>/conf.d/*.json` |
| `--env-file` (repeatable) | — | none |
| `--log-level` (`debug`\|`info`\|`warn`\|`error`\|`silent`) | `DB_ACCESS_MCP_LOG_LEVEL` | `info` |

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

| Tool | What it does |
|---|---|
| `dialect_list` | Lists the supported database dialects: name (the `type` value for connections), default port and the plan format `query_plan` produces. |
| `connection_list` | Lists configured connections: key, type, description, `read_only`, host/port/database, tunnel name, metadata. Credentials are **never** returned (allowlist-based sanitization; connection strings are parsed only for host/port/database). |
| `connection_find` | Finds connections by `host`, `port`, `database`, `type`, `read_only` and/or `metadata` key-value pairs. All filters are combined with **AND**. `user`/`password` filters are ignored (and noted in the response). |
| `connection_test` | End-to-end health check: secrets → tunnel → pool → one-row server-info query. Returns `ok: true` with server version/user/database/latency, or `ok: false` with the failure code and hint (an unreachable DB is a valid result, not a tool error). |
| `query` | Executes SQL on a connection. Accepts `connection`, `query`, optional `database` (see multi-database connections), `max_rows` and `timeout_ms` overrides. Results are truncated to the row cap with `truncated: true`. |
| `query_to_file` | Executes a query and writes the result to a file (`csv`/`jsonl`, inferred from the extension) instead of the model context. `file_path` is relative to the export dir (default `/tmp/db-access-mcp/exports`, created on demand), or an absolute/`~` path **under** the export dir or a configured `allow_export_paths` root — writes outside are rejected. Existing files require `overwrite: true`. postgres/mysql **stream** rows (no cap by default); redshift/mssql buffer and are capped at 100k rows. |
| `query_plan` | Returns the execution plan without running the query: `EXPLAIN (FORMAT JSON)` for postgres, `EXPLAIN FORMAT=JSON` for mysql, text `EXPLAIN` for redshift, `SHOWPLAN_XML` for mssql. |
| `up_tunnel` | Opens (or reuses) the tunnel configured for a connection and returns `{host, port, tunnel_id, reused}`. Optional `local_port` binds an exact local port; if the tunnel is already open on a different port or the port is taken, the call fails with the current port in the error. |
| `down_tunnel` | Closes a tunnel by `tunnel_id`. By default only the up_tunnel pin is released — if query pools still hold the tunnel it stays open (`remaining_holders`); `force: true` drains the holder pools and closes it unconditionally. |
| `tunnel_list` | Lists the tunnels currently open in this MCP instance with a live health probe: `tunnel_id`, tunnel name/type, local and remote endpoints, `healthy`, holder pools (`connections`), up_tunnel `pins`, external PIDs. |
| `config_reloa