@channel.io/bigquery-mcp

BigQuery MCP

이 패키지는 Google BigQuery API를 사용하여 특정 쿼리를 실행하고, 그 결과를 반환하거나 CSV 파일로 저장하는 Model Context Protocol(MCP) 도구입니다.

기능

• BigQuery 연동: Google BigQuery 서비스와 안전하게 연동합니다.
• 쿼리 실행 및 결과 반환:
  • run_bigquery_query: 지정된 SQL 쿼리를 BigQuery에서 실행하고 결과를 직접 반환합니다.
• 쿼리 결과 다운로드:
  • download_bigquery_query: 지정된 SQL 쿼리를 실행하고, 그 결과를 CSV 파일로 지정된 또는 기본 경로에 저장합니다. 저장된 파일 경로를 반환합니다.
  • download_bigquery_query_transpose: download_bigquery_query와 유사하나, 결과를 CSV로 저장하기 전에 행과 열을 전치(transpose)합니다.
• MCP 서버 기본 설정: MCP 표준을 준수하는 서버 구조를 가집니다.
• TypeScript 설정: 타입 안정성을 위한 TypeScript 기반입니다.
• 서비스 및 도구 분리: 로직을 서비스와 도구 레이어로 분리하여 관리 용이성을 높였습니다.
• 중앙화된 설정 관리: src/config/index.ts를 통해 환경 변수 기반의 설정을 관리합니다.

인증 및 환경 변수

이 MCP 도구를 사용하기 위해서는 Google Cloud Platform (GCP) 인증 설정 및 프로젝트 ID 지정이 필요합니다.

• 필수 환경 변수:

  • BIGQUERY_PROJECT_ID: 쿼리를 실행할 Google Cloud 프로젝트의 ID입니다.

    export BIGQUERY_PROJECT_ID="your-gcp-project-id"
    

• Google Cloud 인증 방법 (다음 중 하나를 선택):

  • 방법 1: 서비스 계정 키 파일 사용 (권장)
    • GCP 서비스 계정을 생성하고, 해당 서비스 계정에 BigQuery 관련 권한(예: BigQuery 데이터 뷰어, BigQuery 사용자 등)을 부여합니다.
    • 서비스 계정 키(JSON 파일)를 다운로드합니다.
    • 다운로드한 서비스 계정 키 파일의 경로를 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 설정합니다.

      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
      

  • 방법 2: 서비스 계정 JSON 문자열 직접 사용
    • 서비스 계정 키의 JSON 내용을 문자열 형태로 BIGQUERY_CREDENTIALS_JSON 환경 변수에 설정합니다. JSON 문자열 내의 특수 문자(예: 줄바꿈, 따옴표)는 올바르게 이스케이프되거나, 전체 문자열을 Base64로 인코딩하여 저장 후 애플리케이션에서 디코딩하는 방식을 고려할 수 있습니다. (현재 구현은 Raw JSON 문자열을 가정합니다.)

      # 예시: 실제 키 값은 매우 길고 복잡합니다.
      export BIGQUERY_CREDENTIALS_JSON='{"type": "service_account", "project_id": "...", ...}'
      

    • 참고: 이 방법은 GOOGLE_APPLICATION_CREDENTIALS보다 우선적으로 사용됩니다. 둘 다 설정된 경우 경고가 표시됩니다.
  • 방법 3: Application Default Credentials (ADC)
    • 위 두 환경 변수가 설정되지 않은 경우, Google Cloud SDK는 ADC를 사용하여 인증을 시도합니다. (예: gcloud auth application-default login으로 로컬 개발 환경 설정, 또는 Cloud Run, GKE 등에서 자동으로 주입되는 서비스 계정 사용)

• 다운로드 디렉토리 (선택 사항):

  • download_bigquery_query 및 download_bigquery_query_transpose 도구를 사용하여 파일을 저장할 때, 기본 저장 경로는 사용자 홈 디렉토리의 Downloads 폴더입니다.
  • 다른 디렉토리를 사용하고 싶다면 BIGQUERY_DOWNLOAD_DIR 환경 변수를 설정하여 원하는 경로를 지정할 수 있습니다.

    export BIGQUERY_DOWNLOAD_DIR="/custom/download/path"
    

프로젝트 구조

apps/bigquery-mcp/
├── src/
│   ├── config/
│   │   └── index.ts            # 환경 변수 로드 및 설정 객체 관리
│   ├── services/
│   │   └── BigQueryService.ts  # BigQuery 클라이언트 초기화 및 핵심 쿼리 실행 로직
│   ├── tools/
│   │   ├── runBigQueryQuery.ts             # 'run_bigquery_query' 도구 정의
│   │   ├── downloadBigQueryQuery.ts        # 'download_bigquery_query' 도구 정의
│   │   └── downloadBigQueryQueryTranspose.ts # 'download_bigquery_query_transpose' 도구 정의
│   └── index.ts                # 메인 진입점 (MCP 서버 초기화 및 도구 등록)
├── package.json
├── README.md
└── tsconfig.json

새 패키지 생성 시 참고사항 (원본 보일러플레이트 기준)

이 패키지를 새로운 MCP 도구의 시작점으로 사용하려면:

• 디렉토리 이름을 변경하고 모든 파일의 bigquery-mcp 참조를 새 이름으로 변경 (현재 프로젝트는 이미 bigquery-mcp로 설정됨)
• package.json의 패키지 이름 업데이트
• package.json에서 "private": true, 부분 제거 (필요시)
• 필요한 의존성 추가
• 서비스 및 도구 디렉토리와 구현 파일 추가

라이선스

Channel 내부용