Gulliver

Gulliver

Test on tiny data before you run on giant data.

An open-source MCP server and CLI that gives AI agents a dress rehearsal for SQL: estimate the cost, fix the slow parts, rehearse on 1% → 3% → 10% of the data, predict what 100% will do, and only run the full query inside a budget.

Website · Quick start · Install · Auto-fix · Guards · CI · Compare · FAQ · Roadmap

Works with Claude Code , Codex , Cursor , Gemini CLI , Claude Desktop, VS Code, Windsurf and any MCP client, on DuckDB , Postgres , BigQuery and Snowflake .

New in 0.3.0: a read-only gate that also blocks side-effect functions, SQL hidden in strings and file

access, with DuckDB sandboxed in the engine. A result guard for personal data and prompt injection in rows. A

runaway guard for loops and per-agent budgets. Lint for CI (SARIF, pre-commit), gulliver fix --verify,

gulliver top, and gulliver review with a GitHub Action. One breaking change: DuckDB can no longer read

files outside the database folder and the current folder unless you allow them

(details). See the changelog.

A real recording of the CLI on the demo database (script: docs/demo.sh).

In *Gulliver's Travels*, Gulliver visits Lilliput, a land of tiny people, and Brobdingnag, a land of giants.

Gulliver does the same with your data: it tries your query in Lilliput first, and only walks into Brobdingnag

when it knows what will happen there.

Why

Agents write SQL that works on a small table and breaks on a big one. They do not know that events has 5 billion rows, that a join multiplies rows, or that a forgotten partition filter scans every day since 2019. Benchmarks score agents on *is the answer right*, never on *what did it cost* or *does it still work at 100x*. One unlucky query can burn a monthly budget.

Gulliver sits between the agent and the warehouse:

Every answer has a status and a next_step, so even small models know what to do next.

Gulliver does not only say no. gulliver_fix rewrites the SQL for the agent and labels every change. same (exactly the same rows) is only claimed when Gulliver has checked the column types on the connection; everything else (assumes, nulls, changes) needs mode=all and says what may differ. With a connection it estimates the old and the new query side by side, so nobody has to trust the saving blindly. With --verify it also tests every rewrite on generated edge-case data and shows a counterexample when the rows differ.

Agents also fail in ways that have nothing to do with size. Gulliver guards those too (details in Guards for agents):

And for the pipeline around the query (details in Pipeline tools and In CI and on pull requests):

Quick start (2 minutes, no warehouse needed)

pip install gulliver-mcp

gulliver demo # creates gulliver_demo.duckdb with 5M events export GULLIVER_DSN=gulliver_demo.duckdb

gulliver inspect gulliver preflight "select country, count(*) from events e join users u on e.user_id = u.user_id group by 1" gulliver lint "select * from events e, users u" # GV003: join without a condition -> blocked gulliver preflight "select * from read_csv('/etc/passwd')" # GS004: a file outside the allowed folders -> blocked gulliver rehearse "select a.event_id, b.event_id from events a join events b on a.user_id = b.user_id"

The last one is the classic agent mistake: a self-join on a non-unique key. The rehearsal predicts the full result (about 255 million rows from a 5-million-row table) and warns that the query multiplies rows, before you run it.

| Sample | Runtime  | Output rows |

|--------|----------|-------------| | 1% | 0.4955s | 2,538,840 | | 3% | 1.2153s | 7,625,948 | | 10% | 4.0825s | 25,531,916 |

Prediction for 100%: output rows 256,655,285 (range 179,658,700 - 384,982,928), confidence high Warning: the query multiplies rows: about 256,655,285 output rows from at most 5,000,000 input rows per table (51x)

The real full run returns 254,966,150 rows.

Add --json to any command for machine-readable output. Exit codes: 0 ok, 1 error, 2 blocked, 3 needs rehearsal or approval, 4 a data check failed, so it also works as a CI check.

Install the MCP server

Gulliver is an MCP server (stdio or Streamable HTTP), published on PyPI and npm. Run it with uv, or through npx (which uses uv under the hood):

uvx gulliver-mcp --dsn path/to/warehouse.duckdb

npx -y gulliver-mcp --dsn path/to/warehouse.duckdb

Point it at a database with --dsn, or at a gulliver.toml with connections and budgets (--config). No warehouse yet? Run gulliver demo and use gulliver_demo.duckdb.

Claude Code

claude mcp add gulliver -- uvx gulliver-mcp --dsn /abs/path/data.duckdb

Or install it as a plugin, which adds the MCP server and a skill with the rehearsal workflow:

/plugin marketplace add laaielichter/gulliver

/plugin install gulliver@gulliver

Claude Desktop, Cursor and Windsurf

Add this to the client's MCP config (claude_desktop_config.json, ~/.cursor/mcp.json or ~/.codeium/windsurf/mcp_config.json):

{

"mcpServers": { "gulliver": { "command": "uvx", "args": ["gulliver-mcp", "--config", "/abs/path/gulliver.toml"] } } }

VS Code

In .vscode/mcp.json:

{

"servers": { "gulliver": { "type": "stdio", "command": "uvx", "args": ["gulliver-mcp", "--config", "/abs/path/gulliver.toml"] } } }

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.gulliver]

command = "uvx" args = ["gulliver-mcp", "--config", "/abs/path/gulliver.toml"]

Gemini CLI

In ~/.gemini/settings.json, the same mcpServers block as for Claude Desktop above.

Any HTTP client or remote agent

gulliver-mcp --http --port 8765 serves http://127.0.0.1:8765/mcp (Streamable HTTP).

Without MCP: OpenAI and Gemini function calling

Every tool is also a CLI command with --json, and gulliver tools --format openai or --format gemini prints ready-made function-calling definitions for the OpenAI or Gemini APIs.

More of MCP than tools

All 16 tool schemas take about 25.6 KB of the agent's context. gulliver-mcp --toolset core loads only the 8 query tools (about 10.9 KB); --toolset pipeline loads the pipeline tools; a comma list mixes sets and tool names. The server also offers resources (gulliver://rules, gulliver://status, table metadata, receipts), prompts (safe-query-loop, refactor-and-prove, make-incremental), progress during a rehearsal, and a typed outputSchema on every tool.

A human can let approvals ha