tusk-mcp

Read-only PostgreSQL MCP server for AI agents. Exposes schema introspection and SELECT-only query execution over the Model Context Protocol.

Install

# npx (no install needed)
npx tusk-mcp --host db.example.com --database mydb

# or clone + run
bun install
bun run src/index.ts --host localhost --database mydb

Related MCP server: mcp-postgres

Setup UI

Interactive browser-based setup that generates config for Claude Desktop, Claude Code, Cursor, Windsurf, and OpenAI Codex.

npx tusk-mcp setup

Build standalone binary

bun run build           # Windows
bun run build:linux     # Linux
bun run build:macos     # macOS ARM

Connection

Individual flags (recommended)

tusk-mcp --host db.example.com --port 5432 --user admin --password 'p@ss' --database mydb

Connection string

tusk-mcp --connection-string "postgres://admin:p%40ss@db.example.com:5432/mydb"

Unencoded special characters in passwords (@, #) are handled automatically.

Environment variables

PGHOST=db.example.com PGDATABASE=mydb tusk-mcp

Priority: flags > --connection-string > DATABASE_URL > PG* env vars

Multiple environments / databases

A config file defines named targets: environments (local/stage/prod) or entirely different databases within one app. tusk.config.jsonc or tusk.config.json in the working directory is picked up automatically when no connection flags are given; --config <path> (relative or absolute) loads an explicit file. Connection flags cannot be combined with a config file.

{
  "defaultTarget": "local",          // used when a tool call omits target
  "defaults": {                      // merged under every target
    "user": "app",
    "database": "myapp"
  },
  "targets": {
    "local": { "host": "localhost", "description": "dev" },
    "stage": {
      "host": "stage.db.internal",
      "password": "${STAGE_DB_PASSWORD}",   // env var interpolation
      "ssl": true
    },
    "prod": {
      "connectionString": "postgres://ro:${PROD_DB_PASSWORD}@10.0.0.5:5432/myapp",
      "ssh": { "host": "bastion.example.com", "user": "deploy", "key": "~/.ssh/id_rsa" },
      "structureOnly": true,                // per-target: schema visible, queries disabled
      "description": "production"
    },
    "analytics": { "host": "warehouse.db", "database": "events" }
  }
}

Target fields mirror the CLI flags: host, port, user, password, passwordFile, passwordCmd, database, connectionString, ssl (true or {ca, cert, key} paths), ssh ({host, port, user, key, password}), structureOnly, description.

Priority: explicit fields > connectionString > defaults. ssh/ssl objects deep-merge, so defaults.ssh can hold the shared bastion and a target override just the port. ${VAR} interpolates from the environment in any string, so the file is safe to commit. Config-file targets ignore PG* env vars; use ${PGPASSWORD} explicitly if wanted.

With multiple targets every tool takes a target enum parameter (optional when defaultTarget is set, absent entirely with a single target), the target list is announced via MCP instructions, and compare-schemas becomes available. Connections are lazy per target: an unreachable bastion never blocks startup or the other targets.

Password security

# From file (Docker/K8s secrets)
tusk-mcp --host db --database mydb --password-file /run/secrets/db_pass

# From command (any secrets manager)
tusk-mcp --host db --database mydb --password-cmd 'vault kv get -field=password secret/db'
tusk-mcp --host db --database mydb --password-cmd 'op read op://vault/db/password'

SSL

Providing any certificate file automatically enables SSL.

tusk-mcp --host db --database mydb --ssl-ca /path/to/ca.crt       # CA verification
tusk-mcp --host db --database mydb \                               # mutual TLS
  --ssl-ca ca.crt --ssl-cert client.crt --ssl-key client.key

SSH tunnel

tusk-mcp --host db-internal --database mydb \
  --ssh-host bastion.example.com --ssh-user deploy --ssh-key ~/.ssh/id_rsa

Structure-only mode

Agents see schema but cannot run queries. The --structure-only flag applies it to every target; per-target structureOnly in the config file keeps execute-query registered and rejects calls against that target only. When all targets are structure-only the tool is not registered at all.

tusk-mcp --host db --database mydb --structure-only

Tools

Output format

Tool results use compact text in content for the AI model and JSON-safe preview data in structuredContent for clients that support structured MCP output. Query text uses a tab-delimited preview with null=\N; strings are JSON-quoted, so empty strings render as "" and the literal string "\\N" is distinct from SQL null. With multiple targets, results start with a target=<name> line.

MCP config

{
  "mcpServers": {
    "tusk": {
      "command": "npx",
      "args": ["-y", "tusk-mcp", "--host", "localhost", "--database", "mydb"]
    }
  }
}

Claude Code

claude mcp add --transport stdio tusk -- npx -y tusk-mcp --host localhost --database mydb

OpenAI Codex (~/.codex/config.toml)

[mcp_servers.tusk]
command = "npx"
args = ["-y", "tusk-mcp", "--host", "localhost", "--database", "mydb"]

All flags