Quarry MCP server

Quarry

The database workbench built for the AI era — one kernel, many faces (CLI / GUI / MCP / agent skill).

中文文档 → · Website →

Every database tool you know — DBeaver, TablePlus, pgAdmin — assumes a human at the keyboard. But increasingly, the entity running your queries is an AI agent, and agents need different guarantees:

• Results a machine can parse, not a screen a human can read
• Shared query safety policies, with explicit authorization by entry point
• Deterministic error contracts (stable exit codes), not stack traces to scrape
• Configuration as files, not clicks — so it can be versioned, diffed, and shared with agents

Quarry inverts the traditional design: it is a query kernel with an agent-safe contract first, and the human faces (CLI, GUI) are thin shells grown from the same kernel. Whether a query comes from a person in the browser, a script in CI, or Claude running a skill, it uses shared query policies. CLI formats render rows; the GUI, MCP and Python API expose a structured QueryResult. See the interface and support contract for the exact boundaries.

Philosophy

1. One core, many faces. Connection management, query execution, schema introspection, and safety rails live in an importable kernel (quarry.core). The CLI (qy), the GUI, the MCP server, and agent skills are thin shells. Fix a bug once, every face gets it.

1. Read-only by default; escalation is explicit and graduated. CLI writes require --write; prod additionally needs confirmation or --yes. MCP requires server and per-call authorization, plus confirmprod for prod. GUI queries are read-only; Python callers obtain authorization before passing allowwrite=True. Read queries without an outer LIMIT default to a 500-row cap; --max-rows 0 explicitly disables it. PostgreSQL/MySQL query execution also uses database read-only transactions unless writes are authorized.

1. A contract machines can trust. GUI/MCP/Python queries return {columns, rows, rowCount, truncated, elapsedMs, engine, sql, downloadBytes, sizeIsEstimated}. CLI JSON remains an array of rows; diagnostics and truncation notices go to stderr. Exit codes are stable API: 0 ok, 2 connection error, 3 SQL error, 8 safety block. CLI argument syntax errors also use 2; other commands have their own codes (for example ping returns 1 on failure). GUI/MCP/Python report structured errors.

1. Workspace as code. A workspace is just a directory: connections.toml + queries//.sql (named queries with -- @meta headers). Share query files and credential-free templates through your repo; keep actual connection credentials local.

1. Nearly zero dependencies. The base package and GUI use Python 3.11+ stdlib. PostgreSQL uses system psql, Redis needs redis-cli 6+, SSH uses system ssh, and MySQL uses the optional quarry-db[mysql] dependencies. No Electron or cloud service; the optional qy up keeper runs in the background.

Install

pipx install quarry-db        # or: pip install quarry-db
qy --help

PostgreSQL uses the system psql binary; MySQL needs pip install "quarry-db[mysql]".

Quickstart

mkdir my-workspace && cd my-workspace
cat > connections.toml <<'EOF'
[shop]
url    = "postgresql://user:pass@localhost:5432/shop"
engine = "postgres"
env    = "dev"
EOF

Shortened. The full README is on GitHub.