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 지정이 필요합니다.

1. 필수 환경 변수:

- BIGQUERY_PROJECT_ID: 쿼리를 실행할 Google Cloud 프로젝트의 ID입니다.
``bash
export BIGQUERY_PROJECT_ID="your-gcp-project-id"
`

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

- 방법 1: 서비스 계정 키 파일 사용 (권장)
- GCP 서비스 계정을 생성하고, 해당 서비스 계정에 BigQuery 관련 권한(예: BigQuery 데이터 뷰어, BigQuery 사용자 등)을 부여합니다.
- 서비스 계정 키(JSON 파일)를 다운로드합니다.
- 다운로드한 서비스 계정 키 파일의 경로를 GOOGLE_APPLICATION_CREDENTIALS 환경 변수에 설정합니다.
`bash
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-file.json"
`
- 방법 2: 서비스 계정 JSON 문자열 직접 사용
- 서비스 계정 키의 JSON 내용을 문자열 형태로 BIGQUERY_CREDENTIALS_JSON 환경 변수에 설정합니다. JSON 문자열 내의 특수 문자(예: 줄바꿈, 따옴표)는 올바르게 이스케이프되거나, 전체 문자열을 Base64로 인코딩하여 저장 후 애플리케이션에서 디코딩하는 방식을 고려할 수 있습니다. (현재 구현은 Raw JSON 문자열을 가정합니다.)
`bash
# 예시: 실제 키 값은 매우 길고 복잡합니다.
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 등에서 자동으로 주입되는 서비스 계정 사용)

3. 다운로드 디렉토리 (선택 사항):
- download_bigquery_query 및 download_bigquery_query_transpose 도구를 사용하여 파일을 저장할 때, 기본 저장 경로는 사용자 홈 디렉토리의 Downloads 폴더입니다.
- 다른 디렉토리를 사용하고 싶다면 BIGQUERY_DOWNLOAD_DIR 환경 변수를 설정하여 원하는 경로를 지정할 수 있습니다.
`bash
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 도구의 시작점으로 사용하려면:

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

라이선스

Channel 내부용