Skip to content
MCP server

BigQuery MCP

Read-only BigQuery access for agents with a per-query byte limit

Runs locallyStatus and history
Pricing
Open source
Platforms
vscode, CLI, self-hosted
Runs
Locally
Version
26.11.14
Listing updated
3 days ago

About BigQuery MCP

BigQuery MCP is an open-source MCP server for databases. It runs locally on your machine and is started by your AI client.

Every query is dry-run first, and one that would scan more than the ceiling is refused before it costs anything. The default ceiling is 1 GB, set through bigqueryMcp.maxBytesBilled or BIGQUERY_MCP_MAX_BYTES_BILLED. Only a single SELECT statement runs, and results are capped at 1,000 rows per call.

It ships as a VS Code extension that registers itself with the agents it finds: Copilot, Claude Code, Cursor, Codex, Gemini, Windsurf, Continue.dev and Cline. It is also on npm for any MCP client and needs Node.js 22 or newer. Credentials come from an OAuth client, a service account key file or gcloud Application Default Credentials.

The page says it is independent of Google's own managed BigQuery server, runs on your machine, and has no telemetry.

Install

Run in a terminal

claude mcp add bigquery-mcp --env GOOGLE_OAUTH_CLIENT_SECRET='<GOOGLE_OAUTH_CLIENT_SECRET>' --env GOOGLE_OAUTH_REFRESH_TOKEN='<GOOGLE_OAUTH_REFRESH_TOKEN>' -- npx -y @renzo.johnson/bigquery-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "bigquery-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@renzo.johnson/bigquery-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRET": "<GOOGLE_OAUTH_CLIENT_SECRET>",
        "GOOGLE_OAUTH_REFRESH_TOKEN": "<GOOGLE_OAUTH_REFRESH_TOKEN>"
      }
    }
  }
}

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "bigquery-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@renzo.johnson/bigquery-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRET": "<GOOGLE_OAUTH_CLIENT_SECRET>",
        "GOOGLE_OAUTH_REFRESH_TOKEN": "<GOOGLE_OAUTH_REFRESH_TOKEN>"
      }
    }
  }
}

Add to .vscode/mcp.json

{
  "servers": {
    "bigquery-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@renzo.johnson/bigquery-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRET": "<GOOGLE_OAUTH_CLIENT_SECRET>",
        "GOOGLE_OAUTH_REFRESH_TOKEN": "<GOOGLE_OAUTH_REFRESH_TOKEN>"
      }
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "bigquery-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@renzo.johnson/bigquery-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRET": "<GOOGLE_OAUTH_CLIENT_SECRET>",
        "GOOGLE_OAUTH_REFRESH_TOKEN": "<GOOGLE_OAUTH_REFRESH_TOKEN>"
      }
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "bigquery-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@renzo.johnson/bigquery-mcp"
      ],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRET": "<GOOGLE_OAUTH_CLIENT_SECRET>",
        "GOOGLE_OAUTH_REFRESH_TOKEN": "<GOOGLE_OAUTH_REFRESH_TOKEN>"
      }
    }
  }
}

Configuration

  • GOOGLE_APPLICATION_CREDENTIALSPath to a service account key or authorized_user JSON file. Optional if you use gcloud Application Default Credentials or the OAuth variables.
  • GOOGLE_OAUTH_CLIENT_IDOAuth client ID. Set together with the client secret and refresh token.
  • GOOGLE_OAUTH_CLIENT_SECRETOAuth client secret.
  • GOOGLE_OAUTH_REFRESH_TOKENOAuth refresh token with the BigQuery scopes.
  • BIGQUERY_MCP_PROJECT_IDGoogle Cloud project ID used when a request does not name one.
  • BIGQUERY_MCP_MAX_BYTES_BILLEDLargest number of bytes a query may scan (default 1000000000).

Tools this server provides (4)

Taken from the project documentation; the running server may differ.

bq_list_datasets
Lists the datasets in a project.
bq_list_tables
Lists the tables and views in a dataset.
bq_get_table
Gets a table's schema, row count, size and description.
bq_query
Runs a read-only SQL SELECT with optional location, dry run and up to 1,000 rows.

What it does

Spending guard
Dry-runs each query and refuses those over the byte ceiling.
SELECT only
Rejects anything other than a single SELECT statement.
Schema reads
Returns a table's schema, row count, size and description.
Dry-run switch
Lets the agent ask how many bytes a query would scan.
Multi-agent registration
The extension writes config for eight agents.

Good for

  • Ask questions of a GA4 export in plain language
  • Estimate the cost of a query before running it
  • Read table schemas before writing application SQL
  • Find the largest tables in a dataset

Pricing

Open source

Free and MIT licensed; Google Cloud charges apply separately

Prices change. Check renzojohnson.com before you buy.

BigQuery MCP FAQ

Can it modify tables?

No; statements other than a single SELECT are rejected.

How is it licensed?

MIT, free; BigQuery charges are separate.

Where does data go?

Only to Google; the server runs locally with no telemetry.

Is BigQuery MCP free?

Yes. BigQuery MCP is open source, so you can use and self-host it for free.

How do I add BigQuery MCP to Claude Code?

Run this command in your terminal: claude mcp add bigquery-mcp --env GOOGLE_OAUTH_CLIENT_SECRET='<GOOGLE_OAUTH_CLIENT_SECRET>' --env GOOGLE_OAUTH_REFRESH_TOKEN='<GOOGLE_OAUTH_REFRESH_TOKEN>' -- npx -y @renzo.johnson/bigquery-mcp

What are the best alternatives to BigQuery MCP?

The closest alternatives to BigQuery MCP are Agent-Native Analytics, Google Ads + Meta Ads + SEO/GEO MCP, Tapetide - Indian Stock Market MCP, Midplane and World Monitor.

Alternatives to BigQuery MCP

  1. Open-source analytics app where an AI agent builds charts and dashboards from your data

    • Remote
    • Open source
    • 7.7K GitHub stars
    • Analytics and data
  2. Hosted MCP connector for managing Google Ads, Meta Ads, GA4 and Search Console from chat

    • 8 tools
    • Remote
    • Freemium
    • 8.1K GitHub stars
    • Marketing and SEO
  3. Indian NSE and BSE stock market data for AI assistants through 48 MCP tools

    • 17 tools
    • Remote
    • Freemium
    • 150 GitHub stars
    • Finance and payments
  4. Midplane

    MCP server

    Postgres gateway for AI agents with table grants, column masking and approval for writes

    Runs locally
    • Open source
    • 5 GitHub stars
    • Databases
  5. World Monitor

    MCP server

    Live geopolitical intelligence dashboard with an API and MCP server for agents

    • Remote
    • Freemium
    • Analytics and data
  6. CompanyData

    MCP server

    Search and enrich company records from official registers via the CompanyData API

    • 3 tools
    • Remote
    • Paid
    • 3 GitHub stars
    • Analytics and data