mcp-bigquery-server MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

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

라이브 데모

실제 사용 모습

bigquery-server.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/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
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

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

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

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

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

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

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

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

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

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

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

context_servers에 추가. 저장 시 Zed가 핫 리로드.

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

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mcp-bigquery-server

Answer product/growth questions from BigQuery without writing SQL

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

언제 쓸까: You have a question whose answer lives in events tables in BQ.

사전 조건

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

흐름

Discover tables

List tables in dataset analytics. Describe events and users.✓ 복사됨

→ Schemas
Ask the question

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

→ Numeric answer with SQL shown
Caveat

Any caveats? Timezone, deletion, test users?✓ 복사됨

→ Honest caveats

결과: Answers in minutes instead of data-team tickets.

함정

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

언제 쓸까: You want to open BQ access to more people via chat without each of them being able to read customer emails.

흐름

Configure restricted fields

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

→ 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.✓ 복사됨

→ Block on raw read; allow on aggregate

결과: Safer self-service analytics for the LLM era.

함정

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

함께 쓰기: gateway

Auto-compile a daily metrics digest from BQ

👤 PMs, founders ⏱ ~30 min intermediate

언제 쓸까: You want KPIs in Slack every morning without a BI tool.

흐름

Define the metrics

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

→ SQL per metric
Run and format

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

→ Slack-ready message

결과: Daily metrics without managed BI cost.

함께 쓰기: notion

조합

다른 MCP와 조합해 10배 효율

bigquery-server + notion

Weekly KPI doc

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

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.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
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

비용 및 제한

운영 비용

API 쿼터: BigQuery job quotas (generous)
호출당 토큰: Query results can be huge — always LIMIT or aggregate
금액: Pay GCP by bytes scanned ($6.25/TB on-demand). Configure scan limit in MCP to cap.
팁: Filter by partition. A full-table scan on a busy fact table = real money. The MCP's byte limit is your safety net.

보안

권한, 시크릿, 파급범위

최소 스코프: bigquery.dataViewer + bigquery.jobUser on specific datasets only

자격 증명 저장: Service account JSON in a mounted path; never commit

데이터 외부 송신: Query results go to your LLM provider

절대 부여 금지: 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.

문제 해결

자주 발생하는 오류와 해결

PERMISSION_DENIED on dataset

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

확인: 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.

대안

mcp-bigquery-server 다른 것과 비교

대안	언제 쓰나	단점/장점
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

mcp-bigquery-server