Quarry

What quarry does

The quarry MCP server gives AI agents a database-facing MCP interface built on Quarry's shared query kernel. It supports PostgreSQL, MySQL, SQLite, and Redis connections defined in a workspace. The MCP face exposes structured operations for discovering connections, inspecting tables, running SQL, and executing saved queries.

Quarry belongs in the 🗄️ Databases category because it is designed for agent access to existing database systems rather than for storing data itself. It can be useful when an agent needs to answer questions from operational data, inspect a schema before generating SQL, or run a predefined query from a versioned workspace.

How it works

Run qy mcp to start the MCP server over standard input and output. The server uses the same kernel and safety behavior as Quarry's CLI, GUI, and Python API. Its six MCP tools are list_connections, list_tables, describe_table, exec_sql, list_saved_queries, and run_saved_query.

MCP calls are read-only unless the server starts with --write and the individual call includes write: true. Access to a production environment also requires confirm_prod: true. Read queries without an outer LIMIT default to a 500-row maximum; callers can change or disable that limit through the supported query options. Structured results include columns, rows, row counts, truncation status, elapsed time, engine, SQL, and download-size fields where applicable.

Setup and configuration

Install the package with pipx install quarry-db or pip install quarry-db, then create a workspace containing connections.toml. The workspace can also contain saved SQL files under queries/<db>/*.sql. Quarry resolves the workspace from --workspace PATH, the user configuration file, or the current directory.

Start the quarry MCP server with a workspace path:

qy mcp --workspace /path/to/workspace

A client configuration can invoke qy as the command and pass mcp plus the workspace path as arguments. The README gives a Claude Code example using claude mcp add quarry -- qy mcp --workspace ~/my-workspace. PostgreSQL requires the system psql binary, MySQL requires the optional MySQL package dependencies, SQLite uses Python's built-in support, and Redis requires redis-cli 6 or newer.

Tools and capabilities

• List configured database connections.
• List tables and describe table structure.
• Execute ad-hoc SQL through exec_sql.
• List and run saved queries.
• Apply read limits and explicit write authorization.
• Return structured query results and errors for agent consumption.

Limitations and notes

The quarry MCP server communicates over stdio rather than a network HTTP endpoint. Writes are not available by default and require multiple authorization conditions for production data. SQLite connections must point to existing files; Quarry does not create a missing database file. Remote SQLite files, in-memory databases, SQLite URI options, and attached databases are outside the documented first implementation.

The server is distributed under the MIT license. Credentials belong in the local connection configuration rather than shared query templates, so workspace files can contain credential-free connection and query definitions.