mcp-bigquery-server MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Read-only SQL — no INSERT/UPDATE/DELETE/DDL
Configurable query scan limit (default 1 GB) to avoid runaway costs
Field-level restrictions — list sensitive columns; agent can aggregate but not read rows
Schema exploration with table/view differentiation
Service account JSON or gcloud CLI auth

Demo ao vivo

Como fica na prática

bigquery-server.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "bigquery-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ],
      "_inferred": true
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "bigquery-server",
      "command": "npx",
      "args": [
        "-y",
        "mcp-bigquery-server"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "bigquery-server": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-bigquery-server"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add bigquery-server -- npx -y mcp-bigquery-server

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: mcp-bigquery-server

Answer product/growth questions from BigQuery without writing SQL

👤 PMs, growth analysts with BQ-backed warehouse ⏱ ~15 min intermediate

Quando usar: You have a question whose answer lives in events tables in BQ.

Pré-requisitos

GCP service account with BQ Data Viewer + Job User — IAM > Create service account; download JSON key

Fluxo

Discover tables

List tables in dataset analytics. Describe events and users.✓ Copiado

→ Schemas
Ask the question

How many users who signed up in March 2026 triggered the 'aha_moment' event within 7 days?✓ Copiado

→ Numeric answer with SQL shown
Caveat

Any caveats? Timezone, deletion, test users?✓ Copiado

→ Honest caveats

Resultado: Answers in minutes instead of data-team tickets.

Armadilhas

Running SELECT * on a huge fact table blows the scan limit — Always filter by partition column (often _PARTITIONDATE)

Let a less-trusted analyst explore data without reading PII rows

👤 Data platform teams ⏱ ~30 min advanced

Quando usar: You want to open BQ access to more people via chat without each of them being able to read customer emails.

Fluxo

Configure restricted fields

Add config.json entry restricting fields users.email, users.phone, users.ssn. Agent can only aggregate these, not SELECT them raw.✓ Copiado

→ Config in place
Test

Run SELECT email FROM users LIMIT 10. Verify it's blocked. Then run SELECT domain, COUNT(*) FROM users GROUP BY domain — verify it works.✓ Copiado

→ Block on raw read; allow on aggregate

Resultado: Safer self-service analytics for the LLM era.

Armadilhas

Regex-based field detection can miss complex aliased SQL — Defense in depth — also use BQ column-level security / authorized views

Combine com: gateway

Auto-compile a daily metrics digest from BQ

👤 PMs, founders ⏱ ~30 min intermediate

Quando usar: You want KPIs in Slack every morning without a BI tool.

Fluxo

Define the metrics

Define queries for: DAU, signups, revenue, top-3 errors. Each with yesterday / 7-day avg.✓ Copiado

→ SQL per metric
Run and format

Run all and format as a Slack-ready digest. Include week-over-week deltas.✓ Copiado

→ Slack-ready message

Resultado: Daily metrics without managed BI cost.

Combine com: notion

Combinações

Combine com outros MCPs para 10× de alavancagem

bigquery-server + notion

Weekly KPI doc

Run my weekly KPI queries and create a Notion page in 'Metrics Weekly' with results + commentary.✓ Copiado

bigquery-server + gateway

PII-safe access via mcp-gateway + Presidio

Put BigQuery MCP behind mcp-gateway with Presidio; verify customer emails get redacted in results.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_datasets		First step to orient	free
list_tables	dataset	Navigate a dataset	free
describe_table	dataset, table	Before querying	free
query	sql: str, max_bytes?: int	Main read tool; limited to 1GB scan by default	BQ on-demand: $6.25 per TB scanned

Custo e limites

O que custa rodar

Cota de API: BigQuery job quotas (generous)
Tokens por chamada: Query results can be huge — always LIMIT or aggregate
Monetário: Pay GCP by bytes scanned ($6.25/TB on-demand). Configure scan limit in MCP to cap.
Dica: Filter by partition. A full-table scan on a busy fact table = real money. The MCP's byte limit is your safety net.

Segurança

Permissões, segredos, alcance

Escopos mínimos: bigquery.dataViewer + bigquery.jobUser on specific datasets only

Armazenamento de credenciais: Service account JSON in a mounted path; never commit

Saída de dados: Query results go to your LLM provider

Nunca conceda: dataOwner / dataEditor to the MCP's service account

Field restrictions are cooperative guardrails for agents — not a replacement for BigQuery IAM/column-level security.
Developer preview status noted by upstream — verify behavior in your setup before prod use.

Solução de problemas

Erros comuns e correções

PERMISSION_DENIED on dataset

SA lacks BQ Data Viewer. gcloud projects add-iam-policy-binding ....

Verificar: gcloud bigquery datasets list

Query exceeds configured byte limit

Add partition filter or column projection; or raise limit if legitimately needed.

Restricted field still appearing in results

Regex match may miss aliased columns — use BQ authorized views for hard isolation.

Alternativas

mcp-bigquery-server vs. outros

Alternativa	Quando usar	Troca
Looker / Metabase	You want a BI tool, not chat	Better dashboards; less conversational
postgres MCP via Cloud SQL	Your analytical data is in Postgres instead	Different engine; Postgres doesn't scale like BQ for big aggregates

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills