New in 0.3.0 A stronger read-only gate, guards for personal data and loops, and a PR review

Test on tiny data before you run on giant data.

Q: Do I need a warehouse to try it?

No. gulliver demo builds a DuckDB database with 5 million events in seconds, and gulliver lint works without any database at all.

Q: Can the agent change or delete data?

Not by default. Only SELECT runs. Writes (CREATE TABLE AS SELECT, INSERT SELECT) need both the call and a human-set allow_write on the connection, and the agent cannot approve its own runs.

Gulliver is an MCP server and CLI that gives AI agents a dress rehearsal for SQL. It estimates the cost, runs the query on 1%, 3% and 10% of the data, predicts the full run, and only lets it run inside your budget.

uvx gulliver-mcp

View on GitHub Set up your agent

Works with Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop, VS Code, Windsurf and any MCP client. Open source, MIT, runs on your machine.

A rehearsal of an agent's self-join

events a join events b on user_id, 5 million rows

2.5 M rows

7.6 M rows

10%

25.5 M rows

100%

≈ 257 M rows

Bars on a log scale. The 100% bar is a prediction, with its range. The real run returned 254,966,150 rows.

The output is 51 times the biggest table: the join on user_id multiplies rows. Gulliver flags it before the full run, not after the bill.

Five steps between your agent and the warehouse

Every answer carries a status and a next_step, so even a small model knows what to do. Limits are set by a human in gulliver.toml; the agent cannot raise them or approve itself.

inspect
See what is big
Rows, bytes, partitions and columns, from metadata only. Free.
preflight
Price it first
Bytes, rows and money without running, plus 15 scale-lint rules and a read-only gate.
rehearse
Try it small
Runs on 1%, 3%, 10% samples and predicts 100% with a range.
run
Run inside budget
Per-query and daily limits. Above a threshold a human approves.
receipt
Show the proof
Estimated, rehearsed, approved, run: predicted versus actual.

The real CLI, on a real table

Recorded on the 5-million-row demo database that gulliver demo builds in seconds. Nothing in this recording is staged.

Terminal recording: Gulliver inspects the demo tables, rehearses a self-join on 1%, 3% and 10% and predicts the size of the full result, then rewrites a DATE(ts) filter into a range on ts with the same rows.

Script: docs/demo.sh

It fixes the SQL, and says what changed

Small models read a lint warning and still write the slow query. gulliver_fix rewrites it for them and labels every change. "Same rows" is only promised when Gulliver has checked the column type on your connection.

same exactly the same rows. The default.
assumes same rows if the column is a date or timestamp without zone.
nulls same rows unless the subquery returns NULL.
changes a different result on purpose, like a LIMIT.

-- GV005, ts is TIMESTAMP: same rows
- where date(ts) = '2025-01-20'
+ where ts >= '2025-01-20'
+   and ts <  '2025-01-21'

-- partitions, indexes and Parquet
-- min/max statistics can now skip data

Every "same" rewrite is tested against real data: NULLs, infinity, leap days, the last microsecond of a day, and time zones that repeat midnight.

Add it to your agent

Point it at a warehouse with --dsn, or at a gulliver.toml with connections and budgets. To try it without a warehouse, run gulliver demo.

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

# or as a plugin, with the skill included
/plugin marketplace add laaielichter/Gulliver
/plugin install gulliver@gulliver

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

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

Prefer npm? Use "command": "npx", "args": ["-y", "gulliver-mcp", ...]. It needs uv on the machine.

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

pip install gulliver-mcp
gulliver demo
gulliver --dsn gulliver_demo.duckdb preflight "select country, count(*) from users group by 1"
gulliver tools --format openai   # function definitions for any API

Also for the pipeline around the query

Sixteen MCP tools in total, each also a CLI command with --json. --toolset core loads only the eight query tools.

gulliver_impactWhat breaks if you change or drop a column: column-level lineage over SQL models or a dbt manifest.

gulliver_driftColumns removed, retyped or added since the last snapshot, and the models they break.

gulliver_diffDo two queries or tables return the same rows? Hashed inside the engine, also across engines.

gulliver_translateSQL between DuckDB, Postgres, BigQuery and Snowflake, with warnings.

gulliver_incrementalCan a full-rebuild model be incremental? The SQL, the dbt config and the rows it saves.

gulliver_checkUnique keys, not null, accepted values, ranges, freshness and row-count jumps in one scan.

gulliver_topThe most expensive repeated queries from query history, with same-rows fixes priced per month.

gulliver_reviewA PR gate for SQL models: new lint, breaking changes, downstream impact and cost per month. Also a GitHub Action.

gulliver lint models/Lint every SQL file in CI: SARIF, GitHub, GitLab and JUnit output, inline ignores, pre-commit hooks.

How it compares

Based on each project's public docs in November 2026. If something is out of date, open an issue.

	Gulliver	cost-guard-mcp	Database MCP servers	dbt-mcp, dbt --sample
Cost before running	Yes, with an accuracy label	BigQuery, Snowflake, Databricks	Limits and timeouts	No
Rehearse on samples, predict 100%	Yes	No	No	dbt only, time windows
Auto-fix with a same-rows guarantee	Yes	No	No	No
Budget gate, human approval, receipt	Yes	No	Read-only modes	No
Blocks side-effect functions and file access in a SELECT	Yes, plus a DuckDB engine sandbox	No	Varies; a read-only database user is strongest	No
Personal data and prompt injection in results	Masked or flagged, rows marked untrusted	No	Some wrap results with a warning	No
Lint and cost review on pull requests	SARIF, GitHub Action	No	No	No
Engines	DuckDB, Postgres, BigQuery and Snowflake (beta)	BigQuery, Snowflake, Databricks	Many	dbt projects

What Gulliver does not do: run your pipelines, replace dbt, or host anything for you. There is no Databricks or ClickHouse engine yet, and BigQuery and Snowflake have only been tested against fakes so far.

Questions people ask

Short answers. The README has the details.

Does Gulliver send my data or my SQL anywhere?

No. It runs on your machine and only talks to the databases you configure. Receipts, the spend ledger and approvals are JSON files in ./.gulliver/. There is no telemetry.

Do I need a warehouse to try it?

No. gulliver demo builds a DuckDB database with 5 million events in seconds, and gulliver lint works without any database at all.

Which agents and models does it work with?

Any MCP client: Claude Code, Codex, Cursor, Gemini CLI, Claude Desktop, VS Code, Windsurf. Without MCP, use the CLI with --json, or gulliver tools --format openai (or gemini) for function calling. Every answer is short JSON with a status and a next_step, so smaller models can follow the loop too.

How accurate is the prediction?

It is a growth curve fitted on three samples, so it comes with a confidence level and a range (x0.7 to 1.5 when confidence is high, up to x0.25 to 4 when it is low). On BigQuery the money estimate uses the exact dry-run bytes of the full query. After a real run, the receipt shows predicted versus actual. Joins and skewed data can grow faster than the data; Gulliver flags that instead of hiding it.

Can the agent change or delete data?

Not by default. Only SELECT runs. Writes (CREATE TABLE AS SELECT, INSERT SELECT) need both the call and a human-set allow_write on the connection, and the agent cannot approve its own runs.

How is this different from EXPLAIN or a BigQuery dry run?

Gulliver uses those for the preflight. On top of that it rehearses on samples to show how runtime and output rows grow, rewrites slow SQL with a stated guarantee, enforces a budget, and writes a receipt, in one JSON format across four engines.

Is it ready for production on BigQuery and Snowflake?

Not yet. Both are beta and have been tested against fakes, not live accounts. DuckDB and Postgres are tested in CI, Postgres against a live server. Reports from real warehouses are very welcome.

What comes next

Ideas, not promises. Each one is open for help.

Live tests for BigQuery and Snowflake, so they can leave beta.
A Postgres check for user functions in untrusted languages or with SECURITY DEFINER (GS005).
More same-rows rewrites in gulliver_fix.
Databricks and ClickHouse engines.

Help build it

Gulliver is young and the issues are small and well described. Seen an agent's SQL go wrong at scale? That example can become the next lint rule.

Good first issues Share a case Contributing guide

Test on tiny data before you run on giant data.

A rehearsal of an agent's self-join

Five steps between your agent and the warehouse

See what is big

Price it first

Try it small

Run inside budget

Show the proof