BigQuery

BigQuery MCP 서버는 Google BigQuery에 액세스할 수 있게 해주는 Model Context Protocol(MCP) 서버입니다. 이 서버를 통해 AI 어시스턴트가 BigQuery 데이터베이스의 스키마를 검사하고 SQL 쿼리를 실행할 수 있습니다. 다양한 구현체가 있으며, 주요 BigQuery MCP 서버 중 두 가지는 LucasHild의 mcp-server-bigquery와 ergut의 mcp-bigquery-server입니다.

특징

• BigQuery 데이터베이스에 안전하고 읽기 전용 액세스 제공
• SQL 쿼리 실행 기능 지원
• 데이터베이스 스키마 검사 기능
• 테이블 목록 조회 및 테이블 세부 정보 확인
• Google Cloud Platform(GCP) 인증 통합
• Claude Desktop 및 기타 MCP 클라이언트와 손쉬운 통합

제공 도구

LucasHild/mcp-server-bigquery 도구

• execute-query: BigQuery 방언을 사용하여 SQL 쿼리 실행
• 필수 매개변수: 실행할 SQL 쿼리

• 반환: 쿼리 결과

• list-tables: BigQuery 데이터베이스의 모든 테이블 목록 조회

• 필수 매개변수 없음

• 반환: 테이블 목록 (ID, 이름, 유형 등)

• describe-table: 특정 테이블의 스키마 설명

• 필수 매개변수: 테이블 이름 또는 ID
• 반환: 테이블 스키마 정보 (필드, 유형, 설명 등)

ergut/mcp-bigquery-server 도구

이 구현체는 자연어로 데이터 질의를 지원하며, 다음 기능을 제공합니다:

• 테이블 및 구체화된 뷰에 액세스
• 데이터셋 스키마 탐색
• 리소스 타입(테이블 vs 뷰) 명확히 표시
• 안전한 제한 내에서 데이터 분석 (기본적으로 1GB 쿼리 제한)
• 보안 데이터 액세스 (읽기 전용)

설치 및 구성 방법

LucasHild/mcp-server-bigquery 설치

Smithery를 통한 자동 설치:

npx -y @smithery/cli install mcp-server-bigquery --client claude

Claude Desktop에 수동으로 추가 (uvx 사용):

{
  "mcpServers": {
    "bigquery": {
      "command": "uvx",
      "args": [
        "mcp-server-bigquery",
        "--project",
        "your-gcp-project-id",
        "--location",
        "your-gcp-location"
      ]
    }
  }
}

ergut/mcp-bigquery-server 설치

Smithery를 통한 자동 설치:

npx @smithery/cli install @ergut/mcp-bigquery-server --client claude

Claude Desktop에 수동으로 추가:

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}

서비스 계정을 사용하는 경우:

{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1",
        "--key-file",
        "/path/to/service-account-key.json"
      ]
    }
  }
}

구성 옵션

LucasHild/mcp-server-bigquery 구성 옵션

• --project (필수): GCP 프로젝트 ID
• --location (필수): GCP 위치 (예: europe-west9)
• --dataset (선택): 특정 BigQuery 데이터셋만 고려. 여러 데이터셋을 지정하려면 인수를 반복해서 사용 (예: --dataset my_dataset_1 --dataset my_dataset_2). 제공되지 않으면 프로젝트의 모든 데이터셋이 고려됨
• --key-file (선택): BigQuery용 서비스 계정 키 파일 경로. 제공되지 않으면 기본 자격 증명이 사용됨

ergut/mcp-bigquery-server 구성 옵션

• --project-id (필수): Google Cloud 프로젝트 ID
• --location (선택): BigQuery 위치, 기본값은 'us-central1'
• --key-file (선택): 서비스 계정 키 JSON 파일 경로

인증 설정

GCP CLI를 사용한 인증 (개발용)

gcloud auth application-default login

서비스 계정 사용 (프로덕션 권장)

1. Google Cloud Console에서 서비스 계정 키 파일 생성
2. 키 파일을 안전한 위치에 저장
3. 구성 시 --key-file 매개변수를 통해 경로 지정

서비스 계정에 필요한 권한: - roles/bigquery.user (권장) - 또는 roles/bigquery.dataViewer와 roles/bigquery.jobUser 모두

사용 사례 및 제한 사항

사용 사례

• 자연어로 데이터베이스 질의
• 대량의 데이터 분석 및 탐색
• 데이터 스키마 이해 및 개요 파악
• 데이터 기반 질문에 대한 실시간 답변 생성

제한 사항

• MCP 지원은 현재 Claude Desktop(개발자 미리보기)에서만 사용 가능
• 연결은 동일한 컴퓨터에서 실행 중인 로컬 MCP 서버로 제한됨
• 쿼리는 읽기 전용으로 1GB 처리 제한이 있음
• 테이블과 뷰가 모두 지원되지만 일부 복잡한 뷰 유형에는 제한이 있을 수 있음

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 경험을 위해 MCP Inspector를 사용하는 것이 좋습니다.

npx @modelcontextprotocol/inspector uv --directory {{PATH_TO_REPO}} run mcp-server-bigquery

또는 ergut의 서버 구현의 경우:

npx @modelcontextprotocol/inspector node /path/to/your/clone/mcp-bigquery-server/dist/index.js --project-id your-project-id --location us-central1

라이선스

두 구현체 모두 MIT 라이선스 하에 제공됩니다.

연결된 구성 요소

• ArangoDB
• Airtable
• MongoDB
• PostgreSQL
• Snowflake