bq-readonly-mcp

🔍 Read-only BigQuery MCP server with auto-LIMIT, dry-run cost guard, and ADC auth. Safe for LLMs to query your BigQuery — no DML, no surprises, no runaway bills.

✨ Why this exists

LLMs connected to BigQuery can accidentally scan terabytes if the MCP layer lets them run arbitrary SQL. bq-readonly-mcp prevents that by design: every query goes through a strict SELECT/WITH-only validator, gets an automatic LIMIT injected before it runs, and is priced via a dry-run before any bytes are billed. If the estimated cost exceeds the cap (default 1 GB), the query is refused outright — before a single byte hits your bill.

The server runs as a local stdio process under your OS account, uses Application Default Credentials, and exposes zero write operations. There is no INSERT, no UPDATE, no DELETE, no DDL — anywhere in the codebase. The only thing it can do is read, and it does that safely.

🛠️ The 7 tools

🚀 Quick start

Recommended — run directly via uvx (no install needed):

uvx bq-readonly-mcp --project your-project-id --location US

From PyPI (persistent install):

uv tool install bq-readonly-mcp
bq-readonly-mcp --project your-project-id --location US

From source:

git clone https://github.com/mariadb-RupeshBiswas/bq-readonly-mcp.git
cd bq-readonly-mcp
uv run bq-readonly-mcp --project your-project-id --location US

For a full walkthrough (five steps from zero), see docs/QUICKSTART.md.

🔐 Authentication

The server uses Application Default Credentials (ADC). Run this once:

gcloud auth application-default login

For non-interactive environments (CI, containers, service accounts), pass a key file:

bq-readonly-mcp --project your-project-id --key-file /path/to/service-account.json

Or set GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json.

🔌 Plug it into your editor

Full walkthroughs for each client — config file paths, JSON snippets, restart steps — are in docs/EDITOR_SETUP.md.

Covered clients: Claude Code, Claude Desktop, Cursor, Windsurf, GitHub Copilot (VS Code), Cline, Continue.dev, Zed, Gemini CLI.

Claude Code — quick example:

claude mcp add --transport stdio bq-readonly -- \
  uvx bq-readonly-mcp --project your-project-id --location US

Or add to ~/.claude.json (global) or .mcp.json (project-level):

{
  "mcpServers": {
    "bq-readonly": {
      "command": "uvx",
      "args": [
        "bq-readonly-mcp",
        "--project", "your-project-id",
        "--location", "US"
      ]
    }
  }
}

Ready-to-paste configs for all supported clients are in mcp-config-examples/.

⚙️ Configuration reference

All flags can also be set via environment variables. CLI flags take precedence over env vars; env vars take precedence over defaults.

🛡️ Safety model

1. SELECT/WITH only — The SQL validator strips comments, then rejects any statement that doesn't start with SELECT or WITH, or that contains DML/DDL keywords (INSERT, UPDATE, DELETE, DROP, CREATE, MERGE, …).
2. Auto-LIMIT — LIMIT N is injected if absent. The caller can raise it up to --max-limit (default 10,000).
3. Dry-run cost guard — Every run_query call first runs a dry-run to estimate cost. Queries exceeding --max-bytes-billed are refused before any bytes are billed.
4. Dataset allowlist — Optional --datasets flag restricts access to named datasets. A startup warning is logged when unset.
5. Defense in depth — maximumBytesBilled is also set on the real job as a server-side backstop.

Full details and threat model → SECURITY.md

🚫 What it does NOT do

• Write operations of any kind (INSERT, UPDATE, DELETE, DDL) — by design, forever
• Vector / embedding search — deferred to a future release
• Multi-project queries — one server, one GCP project
• Job history / audit log access — privacy footgun, intentionally omitted
• Storage API (export, streaming reads)

These are intentional omissions. v0.1 focuses on safe, read-only schema exploration and SQL queries.

🤔 vs other BigQuery MCPs

💻 Development

# Install with dev deps
uv sync --extra dev

# Run unit tests (fast, no BigQuery required)
uv run pytest tests/unit/ -q

# Run integration tests (requires ADC + BigQuery access)
uv run pytest -m integration -q

# Lint
uv run ruff check src tests

# Type check
uv run mypy src

📜 License

MIT — see LICENSE