BigQuery MCP 서버

Google BigQuery에 접근하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 대용량 언어 모델(LLM)이 BigQuery 데이터셋 구조를 이해하고 SQL 쿼리를 실행할 수 있습니다.

특징

인증 및 연결 관리

ADC(애플리케이션 기본 자격 증명) 또는 서비스 계정 키 파일을 지원합니다.
구성 가능한 프로젝트 ID 및 위치 설정
시작 시 인증 검증

도구

질문
- 읽기 전용(SELECT) BigQuery SQL 쿼리 실행
- 구성 가능한 최대 결과 및 청구 바이트
- SELECT가 아닌 쿼리를 방지하기 위한 보안 검사
모든 데이터세트 나열
- 프로젝트의 모든 데이터 세트를 나열합니다.
- 데이터 세트 ID 배열을 반환합니다.
모든 테이블과 데이터 세트를 나열합니다
- 특정 데이터 세트의 모든 테이블을 스키마와 함께 나열합니다.
- datasetId 매개변수가 필요합니다.
- 테이블 ID, 스키마, 시간 분할 정보 및 설명을 반환합니다.
테이블 정보 가져오기
- 테이블 스키마와 샘플 데이터 가져오기(최대 20행)
- 파티션 필터가 있는 파티션 테이블 지원
- 필터가 없는 분할 테이블에 대한 쿼리에 대한 경고
드라이런 쿼리
- 실행 없이 쿼리 유효성을 확인하고 비용을 추정합니다.
- 반품 처리 규모 및 예상 비용

보안 기능

SELECT 쿼리만 허용됩니다(읽기 전용 액세스)
과도한 비용을 방지하기 위해 쿼리 처리에 대한 기본 제한은 500GB입니다.
분할된 테이블에 대한 파티션 필터 권장 사항
인증 자격 증명의 안전한 처리

설치

로컬 설치

지엑스피1

도커 설치

Docker 컨테이너에서 서버를 실행할 수도 있습니다.

# Build the Docker image
docker build -t bigquery-mcp-server .

# Run the container
docker run -it --rm \
  bigquery-mcp-server \
  --project-id=your-project-id

또는 Docker Compose를 사용합니다.

# Edit docker-compose.yml to set your project ID and other options
# Then run:
docker-compose up

MCP 구성

MCP 지원 LLM과 함께 이 서버를 사용하려면 MCP 구성에 추가하세요.

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account-key.json"
      }
    }
  }
}

서비스 계정 키 파일 대신 애플리케이션 기본 자격 증명을 사용할 수도 있습니다.

{
  "mcpServers": {
    "BigQuery": {
      "command": "/path/to/dist/bigquery-mcp-server",
      "args": [
        "--project-id",
        "your-project-id",
        "--location",
        "asia-northeast1",
        "--max-results",
        "1000",
        "--max-bytes-billed",
        "500000000000"
      ]
    }
  }
}

애플리케이션 기본 자격 증명 설정

애플리케이션 기본 자격 증명을 사용하여 인증하려면:

아직 Google Cloud SDK를 설치하지 않았다면 설치하세요.
# For macOS brew install --cask google-cloud-sdk # For other platforms, see: https://cloud.google.com/sdk/docs/install
인증 명령을 실행합니다.
gcloud auth application-default login
BigQuery 프로젝트에 액세스할 수 있는 Google 계정으로 로그인하려면 메시지를 따르세요.
자격 증명은 로컬 컴퓨터에 저장되고 BigQuery MCP 서버에서 자동으로 사용됩니다.

테스트

테스트와 디버깅을 위해 검사기를 사용할 수 있습니다.

npx @modelcontextprotocol/inspector dist/bigquery-mcp-server --project-id={{your_own_project}}

용법

도우미 스크립트 사용

포함된 run-server.sh 스크립트를 사용하면 일반적인 구성으로 서버를 쉽게 시작할 수 있습니다.

# Make the script executable
chmod +x run-server.sh

# Run with Application Default Credentials
./run-server.sh --project-id=your-project-id

# Run with a service account key file
./run-server.sh \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

수동 실행

컴파일된 바이너리를 직접 실행할 수도 있습니다.

# Run with Application Default Credentials
./dist/bigquery-mcp-server --project-id=your-project-id

# Run with a service account key file
./dist/bigquery-mcp-server \
  --project-id=your-project-id \
  --location=asia-northeast1 \
  --key-file=/path/to/service-account-key.json \
  --max-results=1000 \
  --max-bytes-billed=500000000000

예시 클라이언트

예제 Node.js 클라이언트는 examples 디렉토리에 포함되어 있습니다.

# Make the example executable
chmod +x examples/sample-query.js

# Edit the example to set your project ID
# Then run it
cd examples
./sample-query.js

명령줄 옵션

--project-id : Google Cloud 프로젝트 ID(필수)
--location : BigQuery 위치(기본값: asia-northeast1)
--key-file : 서비스 계정 키 파일 경로(선택 사항)
--max-results : 반환할 최대 행 수(기본값: 1000)
--max-bytes-billed : 처리할 최대 바이트 수(기본값: 500000000000, 500GB)

필수 권한

서비스 계정 또는 사용자 자격 증명에는 다음 중 하나가 있어야 합니다.

roles/bigquery.user (권장)

또는 다음 두 가지 모두:

roles/bigquery.dataViewer (테이블 데이터를 읽기 위한)
roles/bigquery.jobUser (쿼리 실행용)

사용 예

쿼리 도구

{
  "query": "SELECT * FROM `project.dataset.table` LIMIT 10",
  "maxResults": 100
}

모든 데이터 세트 나열 도구

// No parameters required

데이터 세트 도구를 사용하여 모든 테이블 나열

{
  "datasetId": "your_dataset"
}

테이블 정보 가져오기 도구

{
  "datasetId": "your_dataset",
  "tableId": "your_table",
  "partition": "20250101"
}

드라이 런 쿼리 도구

{
  "query": "SELECT * FROM `project.dataset.table` WHERE date = '2025-01-01'"
}

오류 처리

서버는 다음에 대한 자세한 오류 메시지를 제공합니다.

인증 실패
권한 문제
잘못된 쿼리
파티션 필터가 없습니다
과도한 데이터 처리 요청

코드 구조

서버는 다음과 같은 구조로 구성되어 있습니다.

src/
├── index.ts              # Entry point
├── server.ts             # BigQueryMcpServer class
├── types.ts              # Type definitions
├── tools/                # Tool implementations
│   ├── query.ts          # query tool
│   ├── list-datasets.ts  # list_all_datasets tool
│   ├── list-tables.ts    # list_all_tables_with_dataset tool
│   ├── table-info.ts     # get_table_information tool
│   └── dry-run.ts        # dry_run_query tool
└── utils/                # Utility functions
    ├── args-parser.ts    # Command line argument parser
    └── query-utils.ts    # Query validation and response formatting

특허

MIT

BigQuery MCP Server

Integrations