MCP Server

The Query Doctor MCP server (@query-doctor/mcp-server) exposes the SQL analyzer and the PGlite/Postgres-backed optimizer as Model Context Protocol tools. Once installed, an agent such as Claude Code can analyze queries, recommend indexes, and read your CI runs by calling real tools backed by a real Postgres planner.

This page covers installing it. The package is published to npm, so the install is a single claude mcp add command — no clone or build.

Prerequisites

• Node.js 18 or newer and npm — npx fetches the package from the registry.
• An MCP client — e.g. Claude Code (claude CLI).
• Docker is optional. It’s only needed if you use the docker provider to run a local Postgres for the live-query tool (find_slow_queries); most setups don’t need it.

Install

Register the published package with Claude Code. npx downloads and runs it on demand:

claude mcp add query-doctor -- npx -y @query-doctor/mcp-server

The -y flag lets npx install the package without an interactive prompt the first time it runs.

Verify it connected:

claude mcp get query-doctor
# Status: ✓ Connected
# Command: npx
# Args: -y @query-doctor/mcp-server

Caution

If Claude Code was already running, restart it so the client spawns the newly registered server. A server registered mid-session does not take effect until the client restarts.

Other MCP clients

Any stdio-capable MCP client works — register the same command. For clients configured by JSON, the equivalent entry is:

{
  "mcpServers": {
    "query-doctor": {
      "command": "npx",
      "args": ["-y", "@query-doctor/mcp-server"]
    }
  }
}

Confirm the server boots (optional)

You can run the server directly to see it start over stdio. It prints a banner to stderr and then waits for a client — press Ctrl-C to stop:

npx -y @query-doctor/mcp-server
# [qd-mcp] query-doctor v0.0.1  node v24.x  pid ...
# [qd-mcp] cwd /your/current/dir
# [qd-mcp] env  QD_PROVIDER=(auto)  QD_DATABASE_URL=(unset)  QD_REPO_ROOT=(unset → uses cwd)
# [qd-mcp] no provider attached at boot — call get_status or bootstrap_demo_db to get started
# [qd-mcp] connected — stdio transport ready

A clean boot with no database attached is correct — the server finds and attaches a database on its own once an agent calls a tool.

Configuration (optional)

The server runs with no extra configuration: it discovers a database to analyze on its own (from your environment, a local .env, or a local Postgres). Set these environment variables on the registration only to point it somewhere specific:

Variable	Purpose
QD_DATABASE_URL	Postgres connection string to analyze a specific database.
QD_REPO_ROOT	Path to the repo whose migrations seed the in-memory database (defaults to the process cwd).
QD_PROVIDER	Force a provider (pglite, docker, pg); defaults to auto-detect.
QD_POSTGRES_IMAGE	Override the Docker Postgres image used by the docker provider.
QD_API_URL	Query Doctor API endpoint for the CI tools (find_regressions, …). Defaults to the public API.
QD_API_TOKEN	Token for the CI tools when the API requires authentication.

claude mcp add query-doctor \
  --env QD_DATABASE_URL="postgres://user:pass@host:5432/db" \
  --env QD_REPO_ROOT="/path/to/your/repo" \
  -- npx -y @query-doctor/mcp-server

Connection strings are redacted in the server’s boot log.

Companion skill (recommended)

The package also ships an agent skill that makes your agent reach for these tools on its own: whenever it writes or reviews code that builds a query, adds a migration, or defines an index, it validates the plan and index choices against the real planner before handing the code back — instead of guessing, and without you having to ask.

Skills are loaded from .claude/skills/. Drop the published skill into your project (or ~/.claude/skills/ for every project):

mkdir -p .claude/skills/query-doctor
curl -fsSL https://unpkg.com/@query-doctor/mcp-server/skill/SKILL.md \
  -o .claude/skills/query-doctor/SKILL.md

Restart your MCP client after adding it. To update later, re-run the curl pinned to the version you upgraded to (https://unpkg.com/@query-doctor/mcp-server@latest/skill/SKILL.md).

Updating

npx caches packages, so to move to a newer release re-register pinned to the latest version:

claude mcp remove query-doctor
claude mcp add query-doctor -- npx -y @query-doctor/mcp-server@latest

Restart your MCP client to pick up the new version.

Removing

claude mcp remove query-doctor

Troubleshooting

• npx prompts to install on first run — add the -y flag (as in the commands above) so it installs without prompting.
• Tools don’t appear in the agent — confirm claude mcp get query-doctor reports ✓ Connected, then restart the client.
• CI tools (find_regressions, get_latest_ci_run, …) return an auth error — set QD_API_TOKEN (and QD_API_URL if you self-host the API) and restart the client.