qh MCP server

qh

A database server for AI agents, built to use as few tokens as possible. It exposes two MCP tools, whatever the number of connections, and names the connections in its MCP instructions:

Supported now: PostgreSQL 13+, MySQL 8.0.16+, MariaDB 10.6+, SQLite and MongoDB (7 and 8). qh serve adds an HTTP server mode with a REST API, and bench/ compares qh with dbhub and with mongodb-mcp-server (see bench/README.md).

Install

Download a binary for Linux, macOS or Windows (amd64 or arm64) from the releases page, unpack it and put qh on your PATH. Each release lists SHA-256 checksums in checksums.txt. The binaries are not signed: on macOS, a binary downloaded with a browser needs xattr -d com.apple.quarantine qh before its first run.

Or run the server image, which starts server mode on port 8765 and keeps its store in the /data volume. Create the master key once and keep it: it decrypts the stored connection strings, so pass the same key every time you recreate the container, for example to upgrade:

openssl rand -base64 32 > qh-master.key && chmod 600 qh-master.key
docker run -d --name qh -p 127.0.0.1:8765:8765 -v qh-data:/data \
  -e QH_MASTER_KEY="$(cat qh-master.key)" ghcr.io/anderson-0/qh:1
docker logs qh   # shows the admin API key once, on first start

front of qh before exposing it to other machines.

• Exposure. API keys travel in plain HTTP, so the example listens on localhost only. Put a TLS proxy in

the Docker host as host.docker.internal; on Linux, add --add-host=host.docker.internal:host-gateway.

• Arguments. Arguments after the image name replace the default serve --http :8765.
• Reaching host databases. Inside the container, localhost is the container itself. Reach a database on

• Health checks. GET /healthz answers ok without a key, for liveness and readiness probes.
• Storage. The image runs as uid 65532:
• a named volume works as shown;
• a bind-mounted directory must be writable by that uid (chown 65532 DIR);
• on Kubernetes, set securityContext.fsGroup: 65532.

Or build it with Go:

go install github.com/anderson-0/qh/cmd/qh@latest

Add a connection

Connections are read-only unless you pass --mode rw. Pass --dsn - to read the connection string from stdin so the password stays out of your shell history:

qh conn add shop --engine postgres --dsn - --description "Orders and customers"

qh conn add local --engine sqlite --dsn ./app.db

qh conn add app --engine mysql --dsn - --description "Product catalogue"

Connection strings are encrypted (AES-256-GCM) in ~/.config/qh/qh.db; the key is ~/.config/qh/master.key (or $QHMASTERKEY). $XDGCONFIGHOME/qh is used instead of ~/.config/qh when $XDGCONFIGHOME is set; set $QH_HOME to use another directory.

Use it from your editor

qh speaks MCP over stdio with qh mcp. Connections you add or edit with qh conn while it runs are used on the agent's next call (not when QH_DSN is set; see below). Some apps don't inherit your shell's PATH; if the server fails to start, use the full path that which qh prints instead of qh.

Claude Code

claude mcp add qh -- qh mcp

Codex CLI

codex mcp add qh -- qh mcp

Gemini CLI

gemini mcp add -s user qh qh mcp

VS Code (GitHub Copilot agent mode)

code --add-mcp '{"name":"qh","command":"qh","args":["mcp"]}'

Shortened. The full README is on GitHub.