cost-guard-mcp

Pre-flight query cost & result-size guardrails for AI agents, across BigQuery and Snowflake — before the query ever runs.

Why

An AI agent using a warehouse MCP can silently trigger a full-table scan that costs hundreds of dollars, or return millions of rows that flood its own context window. No existing warehouse MCP tells the agent "how much will this cost" or "how much data will this return" before running the query.

What makes this different

• Every cost estimate discloses its accuracy tier — PRECISE (BigQuery dryRun), UPPER_BOUND (Snowflake EXPLAIN), or HEURISTIC (Databricks, not yet shipped) — so your agent never over-trusts a heuristic number.
• Per-call bounds — run_query_bounded takes max_bytes_billed / max_rows / max_estimated_cost_usd on each call; no shared session state required.
• Zero infrastructure — a single local stdio process. No database, no gateway, no Docker Compose.

Tools

• describe_engine_capabilities(engine) — what's exact vs. approximate for this engine.
• estimate_query_cost(engine, sql, warehouse?) — pre-flight cost estimate, tagged with its accuracy tier.
• run_query_bounded(engine, sql, max_bytes_billed?, max_rows?, max_estimated_cost_usd?) — refuses to run if the estimate exceeds your bound.

Setup

BigQuery

Set GOOGLE_APPLICATION_CREDENTIALS to a service-account key file path (or run gcloud auth application-default login).

Snowflake

Set SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, SNOWFLAKE_ROLE (required — no default, never ACCOUNTADMIN), and either SNOWFLAKE_PRIVATE_KEY_PATH (preferred) or SNOWFLAKE_PASSWORD (discouraged).

A note on credentials with MCP hosts

Whatever MCP client/host you use (Claude Desktop, etc.) spawns this server as its own subprocess — it does not automatically inherit your shell's environment variables, even if they're set in your .zshrc/.bashrc. Put them directly in the host's server config instead — see .mcp.json.example for the exact block, and the "Use with other AI coding tools" section below for where each specific tool wants it.

Install

uvx cost-guard-mcp

Also published on the official MCP Registry as io.github.mcpsmiths/cost-guard-mcp.

For local development instead:

git clone https://github.com/mcpsmiths/cost-guard-mcp.git
cd cost-guard-mcp
uv sync
uv run cost-guard-mcp

Use with other AI coding tools

cost-guard-mcp is a standard stdio MCP server — any MCP-compatible client works, not just Claude Desktop. Every client ultimately runs the same command/args/env; only the wrapping file format differs, so there's one canonical definition — .mcp.json.example — instead of a separately maintained copy per tool below.

There is no single file every tool reads automatically (each looks in its own location), but three of the four use the exact same mcpServers wrapper .mcp.json.example already has, so those need nothing more than copying it into place. Fill in your real credential values, then:

Codex is the one genuine exception (TOML, not JSON), so it still needs its own block:

[mcp_servers.cost-guard-mcp]
command = "uvx"
args = ["cost-guard-mcp"]

[mcp_servers.cost-guard-mcp.env]
GOOGLE_APPLICATION_CREDENTIALS = "/path/to/service-account.json"
BIGQUERY_PROJECT = "your-project-id"
SNOWFLAKE_ACCOUNT = "your-account"
SNOWFLAKE_USER = "your-user"
SNOWFLAKE_ROLE = "your-role"
SNOWFLAKE_PRIVATE_KEY_PATH = "/path/to/rsa_key.p8"

Known limitations

• Databricks is not yet supported (deferred past v1).
• Snowflake's UPPER_BOUND estimate excludes Cortex AI Function ("AI Credits") cost.
• BigQuery Editions/capacity-billed projects cannot get a dollar estimate — only a byte count (capacity billing has no fixed $/byte rate).

More docs

• ARCHITECTURE.md — component/data-flow map
• DECISIONS.md — why the design looks the way it does
• CONTEXT.md — terminology glossary (BigQuery/Snowflake concepts that sound alike but aren't)
• CHANGELOG.md — release history
• CONTRIBUTING.md / AGENTS.md — contributing and build/test/lint commands
• SECURITY.md — vulnerability reporting

License

MIT