이 페이지는 Cloud Translation API를 통해 번역되었습니다.

MCP, Gemini CLI, 기타 에이전트와 함께 BigQuery 사용

이 가이드에서는 데이터베이스용 MCP 도구 상자를 사용하여 BigQuery 프로젝트를 다양한 통합 개발 환경 (IDE) 및 개발자 도구에 연결하는 방법을 보여줍니다. 대규모 언어 모델(LLM)을 BigQuery와 같은 데이터 소스에 연결하기 위한 개방형 프로토콜인 모델 컨텍스트 프로토콜 (MCP)을 사용하므로 기존 도구에서 직접 SQL 쿼리를 실행하고 프로젝트와 상호작용할 수 있습니다.

Gemini CLI를 사용하는 경우 BigQuery 확장 프로그램을 사용할 수 있습니다. 방법을 알아보려면 Gemini CLI로 개발하기를 참고하세요. Gemini CLI용 맞춤 도구를 빌드하려면 계속 읽으세요.

이 가이드에서는 다음 IDE의 연결 프로세스를 보여줍니다.

커서
Windsurf (이전 명칭: Codeium)
Visual Studio Code(Copilot)
Cline (VS Code 확장 프로그램)
Claude Desktop
Claude code

시작하기 전에

Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.
Google Cloud 프로젝트에서 BigQuery API를 사용 설정합니다.
이 태스크를 완료하는 데 필요한 역할과 권한을 구성합니다. 프로젝트에 연결하려면 BigQuery 사용자 역할 (roles/bigquery.user), BigQuery 데이터 뷰어 역할 (roles/bigquery.dataViewer) 또는 이에 상응하는 IAM 권한이 필요합니다.
환경에 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다.

MCP Toolbox 설치

BigQuery Gemini CLI 확장 프로그램만 사용하려는 경우에는 MCP 도구 상자를 설치할 필요가 없습니다. 필요한 서버 기능이 번들로 제공되기 때문입니다. 다른 IDE 및 도구의 경우 이 섹션의 단계를 따라 MCP 도구 상자를 설치합니다.

이 도구 상자는 IDE와 BigQuery 사이에 있는 오픈소스 모델 컨텍스트 프로토콜 (MCP) 서버 역할을 하며 AI 도구를 위한 안전하고 효율적인 컨트롤 플레인을 제공합니다.

MCP Toolbox의 최신 버전을 바이너리로 다운로드합니다. 운영체제 (OS) 및 CPU 아키텍처에 해당하는 바이너리를 선택합니다. MCP Toolbox 버전 V0.7.0 이상을 사용해야 합니다.
linux/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/linux/amd64/toolbox
VERSION을 MCP Toolbox 버전(예: v0.7.0)으로 바꿉니다.
macOS darwin/arm64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/arm64/toolbox
VERSION을 MCP Toolbox 버전(예: v0.7.0)으로 바꿉니다.
macOS darwin/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/darwin/amd64/toolbox
VERSION을 MCP Toolbox 버전(예: v0.7.0)으로 바꿉니다.
windows/amd64
curl -O https://storage.googleapis.com/genai-toolbox/VERSION/windows/amd64/toolbox
VERSION을 MCP Toolbox 버전(예: v0.7.0)으로 바꿉니다.
바이너리를 실행 가능하게 만듭니다.
```
chmod +x toolbox
```
설치를 확인합니다.
```
./toolbox --version
```

클라이언트 및 연결 설정

이 섹션에서는 BigQuery를 도구에 연결하는 방법을 설명합니다.

독립형 Gemini CLI를 사용하는 경우 확장 프로그램에 필요한 서버 기능이 번들로 제공되므로 MCP 도구 상자를 설치하거나 구성할 필요가 없습니다.

다른 MCP 호환 도구와 IDE의 경우 먼저 MCP 도구 상자를 설치해야 합니다.

Claude code

Claude Code를 설치합니다.
프로젝트 루트에 .mcp.json 파일이 없으면 만듭니다.

구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Claude Code를 다시 시작하여 새 설정을 로드합니다. 다시 열리면 도구에서 구성된 MCP 서버가 감지되었음을 나타냅니다.

Claude Desktop

Claude Desktop을 열고 설정으로 이동합니다.
개발자 탭에서 구성 수정을 클릭하여 구성 파일을 엽니다.

구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

Claude Desktop을 다시 시작합니다.
새 채팅 화면에 새 MCP 서버와 함께 망치 (MCP) 아이콘이 표시됩니다.

Cline

VS Code에서 Cline 확장 프로그램을 열고 MCP Servers 아이콘을 탭합니다.
MCP 서버 구성을 탭하여 구성 파일을 엽니다.

다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

서버가 성공적으로 연결되면 녹색 활성 상태가 표시됩니다.

커서

프로젝트 루트에 .cursor 디렉터리가 없으면 이 디렉터리를 만듭니다.
.cursor/mcp.json 파일이 없으면 이 파일을 만들고 엽니다.

다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

커서를 열고 설정 > 커서 설정 > MCP로 이동합니다. 서버가 연결되면 녹색 활성 상태가 표시됩니다.

Visual Studio Code(Copilot)

VS Code를 열고 프로젝트 루트에 .vscode 디렉터리가 없으면 만듭니다.
.vscode/mcp.json 파일이 없으면 만들고 엽니다.

다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

        {
          "servers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

VS Code 창을 새로고침합니다. MCP 호환 확장 프로그램이 구성을 자동으로 감지하고 서버를 시작합니다.

Windsurf

Windsurf를 열고 Cascade 어시스턴트로 이동합니다.
MCP 아이콘을 클릭한 다음 구성을 클릭하여 구성 파일을 엽니다.

다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

        {
          "mcpServers": {
            "bigquery": {
              "command": "./PATH/TO/toolbox",
              "args": ["--prebuilt","bigquery","--stdio"],
              "env": {
                "BIGQUERY_PROJECT": "PROJECT_ID"
              }
            }
          }
        }

참고: BIGQUERY_PROJECT 환경 변수는 MCP Toolbox에서 사용할 기본 Google Cloud 프로젝트 ID를 지정합니다. 쿼리 실행과 같은 모든 BigQuery 작업은 이 프로젝트 내에서 실행됩니다.

도구 사용하기

이제 AI 도구가 MCP를 사용하여 BigQuery에 연결됩니다. AI 어시스턴트에게 테이블을 나열하거나 테이블을 만들거나 다른 SQL 문을 정의하고 실행해 달라고 요청해 보세요.

LLM에서 사용할 수 있는 도구는 다음과 같습니다.

analyze_contribution: 기여 분석(핵심 동인 분석이라고도 함)을 실행합니다.
ask_data_insights: 데이터 분석을 실행하거나, 인사이트를 얻거나, BigQuery 테이블의 콘텐츠에 관한 복잡한 질문에 답변합니다.
execute_sql: SQL 문을 실행합니다.
forecast: 시계열 데이터를 예측합니다.
get_dataset_info: 데이터 세트 메타데이터 가져오기
get_table_info: 테이블 메타데이터를 가져옵니다.
list_dataset_ids: 데이터 세트를 나열합니다.
list_table_ids: 테이블을 나열합니다.
search_catalog: 자연어를 사용하여 테이블을 검색합니다.

MCP, Gemini CLI, 기타 에이전트와 함께 BigQuery 사용

시작하기 전에

MCP Toolbox 설치

linux/amd64

macOS darwin/arm64

macOS darwin/amd64

windows/amd64

클라이언트 및 연결 설정

Claude code

Claude Desktop

Cline

커서

Visual Studio Code(Copilot)

Windsurf

도구 사용하기