qh

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.

bench/ compares qh with other database MCP servers on the same questions, model and prompts (see bench/README.md). Accuracy was equal in every comparison:

Install

With Homebrew, on macOS or Linux:

brew install anderson-0/tap/qh

Or 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

• Exposure. API keys travel in plain HTTP, so the example listens on localhost only. Put a TLS proxy in front of qh before exposing it to other machines.
• 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 the Docker host as host.docker.internal; on Linux, add --add-host=host.docker.internal:host-gateway.
• 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 $QH_MASTER_KEY). $XDG_CONFIG_HOME/qh is used instead of ~/.config/qh when $XDG_CONFIG_HOME 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"]}'

Claude Desktop, Cursor, Windsurf (Devin Desktop): add this to the app's MCP config file:

{

"mcpServers": { "qh": { "command": "qh", "args": ["mcp"] } } }

Zed: add it under context_servers in ~/.config/zed/settings.json (Windows: %APPDATA%\Zed\settings.json):

{

"context_servers": { "qh": { "command": "qh", "args": ["mcp"] } } }

One connection from the environment

Docker's MCP catalog and the official MCP registry configure a server through environment variables only. When QH_DSN is set, qh mcp serves exactly that one connection and ignores the connections added with qh conn add:

export QH_DSN='postgres://reader:…@db.example.com/shop'

docker run -i --rm -e QH_DSN ghcr.io/anderson-0/qh:1 mcp

Passing -e QH_DSN without a value copies it from your shell, so the password stays out of ps and your shell history. Inside a container localhost is the container itself; reach a database on the Docker host as host.docker.internal (see Install).

• `QH_DSN`: the connection string. The engine comes from its scheme (postgres://, postgresql://, mysql://, mariadb://, mongodb://, mongodb+srv://, sqlite://, file:) or from a path ending in .db, .sqlite or .sqlite3. For any other string, such as user:pw@tcp(host)/db, set QH_ENGINE.
• `QH_ENGINE`: postgres, mysql, mariadb, mongodb or sqlite. It always wins over the inferred engine.
• `QH_NAME`: the connection name agents pass as source (default db).
• `QH_DESCRIPTION`: optional text that tells agents what the database holds.
• `QH_MODE`: ro (default) or rw.

This mode keeps nothing on disk that outlives the process: the store and the query log are a temporary file removed on exit, the random master key exists only in memory, and the data directory and master.key are never created. Connections you add with qh conn are not used while QH_DSN is set. The string is checked at startup but the database is not contacted, so an unreachable database fails per query rather than stopping the server. QH_DSN cannot be combined with --store, QH_STORE_DSN, --server or a non-default --workspace. With docker run --read-only, mount a writable /tmp for the temporary store: --tmpfs /tmp.

Server mode

Run qh for a team or as the backend of a product:

export QH_MASTER_KEY=$(openssl rand -base64 32)   # keep it: it decrypts stored connection strings

qh serve --http :8080 --data-dir /var/lib/qh

On first start qh prints one admin API key (admin API key (shown once): qh_…), or uses QH_BOOTSTRAP_ADMIN_KEY if you set it; that must be a qh_ key whose secret has at least 32 characters (for example one printed by qh key create --scopes admin). Every request needs Authorization: Bearer :

• Workspaces isolate connections. Admin keys manage workspaces and keys and pick a workspace with the X-QH-Workspace header.
• Scopes: query (MCP tools, schema, query), manage (create, change and delete connections; create query/manage keys for the same workspace, which expire no later than the key that creates them), admin (everything).
• Revoking a key (qh key rm ID or DELETE /api/v1/keys/{id}) deletes only that key. Keys it created, and keys those created, keep working until they are revoked or expire: qh checks each key on its own, never the key that created it. qh key rm says so on stderr, and the API sends the same notice in a QH-Warning header. A request already accepted with the revoked key may still finish.
• MCP is served at /mcp (Streamable HTTP). The REST API is under /api/v1; see /api/v1/openapi.json.
• `qh key` and `qh workspace` act on the local store at --home, or on a server with --server/--key (see Remote CLI).

curl -s -X POST localhost:8080/api/v1/workspaces -H "Authorization: Bearer $ADMIN" -d '{"name":"team"}'

curl -s -X POST localhost:8080/api/v1/keys -H "Authorization: Bearer $ADMIN" \ -d '{"workspace":"team","scopes":["query","manage"],"name":"team"}' curl -s -X POST localhost:8080/api/v1/connections -H "Authorization: Bearer $TEAM" \ -d '{"name":"shop","engine":"postgres","dsn":"postgres://reader:…@db.internal/shop"}' claude mcp add --transport http qh http://localhost:8080/mcp --header "Authorization: Bearer $TEAM"

Server mode refuses database addresses on loopback and link-local ranges, including cloud metadata at 169.254.169.254. It also refuses three IPv6 ranges that embed IPv4 addresses: 64:ff9b::/96, 64:ff9b:1::/48 and ::/96. It accepts only TCP connections. If you reach IPv4 databases through NAT64, allow the translated addresses you need: 203.0.113.0/24 becomes --allow-cidr 64:ff9b::cb00:7100/120. Refuse other translation prefixes your network uses, such as 6to4 or Teredo, with --deny-cidr. Use --allow-cidr 127.0.0.0/8 to allow a local database (this does not help when qh runs in a container, because the host's databases are not on the container's loopback; see the host.docker.internal note under Install), and --deny-cidr to block more (for example your private ranges). SQLite is off unless you pass --sqlite-root DIR; files must then live under DIR/ /, so each workspace sees only its own directory. Each API key may run 4 queries at once; an extra request waits up to 10 s for a free slot, then gets HTTP 429.

Server mode ignores PG* environment variables (it unsets them at startup and names them on stderr), and a Postgres connection string may only use these settings: host, port, dbname, user, password, sslmode, sslsni, sslnegotiation, connect_timeout, target_session_attrs, application_name, channel_binding, require_auth, min_protocol_version and max_protocol_version. Settings that read files on the server (passfile, service, sslcert, sslrootcert, …) are refused, and ~/.pgpass and ~/.postgresql/ are not used.

Without --http, qh serve runs in local mode on 127.0.0.1:8765 with no keys, for tools on your own machine. Local mode is unauthenticated: every process on the machine can use it, with all your connections. It only accepts requests addressed to localhost and refuses cross-origin browser requests.

Running several instances

By default qh serve keeps its store in a SQLite file in --data-dir. To run several instances behind a load balancer, point them all at one Postgres database:

export QH_STORE_DSN='postgres://qh@db.internal:5432/qh?sslmode=verify-full'

export QH_STORE_PASSWORD_FILE=/run/secrets/qh-store-password # or put the password in the URL export QH_MASTER_KEY=… # the same key on every instance qh serve --http :8765 --allow-cidr 10.0.0.0/8

• Store contents. qh creates its tables in a qh schema on first start. Instances starting together apply each migration once and create one admin key; only the instance that created it prints it (set QH_BOOTSTRAP_ADMIN_KEY the same on every instance to choose the key yourself).
• Changes are shared. A c