Cloud/GCP

Gemini CLI와 GCP MCP Server 를 통한 GCP BIgquery 조회

달빛궁전- 2025. 7. 10. 09:00
목적 및 배경:
gemini Cli와 Google Cloud MCP Server를 연결하여 복잡한 gcloud CLI 명령어 대신, 일상적인 대화(자연어)를 통해 Google Cloud Platform(GCP) 리소스를 생성, 조회, 수정, 삭제하는 시스템을 구축하는 것을 목표로합니다.

2025년 7월 1일 기준으로 Google Cloud MCP Server 는 Google Cloud의 공식 제품은 없습니다. 각
MCP 서버별로 제약 사항이 다른 상태입니다.

본 문서에서는 기본적인 구축 후 자연어를 이용하여 Bigquery 조회, 분석하는 방안을 작성하였습니다.
또한 해당 MCP는 현재까지 아래와 같은 제약이 있습니다.
Analyze data within safe limits (1GB query limit by default)
Keep your data secure (read-only access)

 

  • PC 설정
    Node.js 설치가 필요합니다.

    아래 공식 사이트에 각 운영체제별 설치법이 가이드 되어 있으니 참고하여 설치합니다.
    https://nodejs.org/ko/download

    본 문서에서는 MAC환경에서 진행하였으므로 MacOS권장 방법으로 설치 진행합니다.
    # nvm 다운로드 및 설치:
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
    
    # Node.js 다운로드 및 설치:
    nvm install 22
    
    # Node.js 버전 확인:
    node -v # "v22.17.0"가 출력되어야 합니다.
    nvm current # "v22.17.0"가 출력되어야 합니다.
    
    npm 버전 확인:
    npm -v # 10.9.2가 출력되어야 합니다.
     
  1. Gemini CLI 설치
    Gemini CLI는 Google의 Gemini 모델을 커맨드 라인 환경에서 사용할 수 있게 해주는 도구입니다. 이 CLI를 통해 MCP 서버에 자연어 명령을 전달하게 됩니다.

    1회성 사용방안 : 
    터미널에 아래 명령어를 입력하여 설치 없이 바로 실행할 수 있습니다.
    ⁠npx https://github.com/google-gemini/gemini-cli

    설치 후 사용 :
    CLI를 자주 사용할 경우, 시스템에 전역으로 설치하는 것을 권장합니다.
    ⁠npm install -g @google/gemini-cli
    gemini

    더 자세한 설치 방법 및 옵션은 공식 GitHub 저장소에서 확인 부탁드립니다.
    설치 공식 docs : https://github.com/google-gemini/gemini-cli

  2. GCP

    SA키를 사용한다고 하면 아래 방안을 진행하며, 계정으로 로그인할 경우는 3번 MCP Server (Google Cloud MCP Server) 설치, 설정 항목으로 진행합니다.

    SA 키 설정방안
    IAM > Service Account > 계정을 생성합니다.


    권한은 Bigquery 사용자로 줍니다.
    아니면 dataviewer, Jobuser로 주어도 됩니다. 


    계정 생성 후 키탭을 선택하여 json 파일을 발급받습니다.



    해당 파일을 다운로드하여 준비합니다.



  3. MCP Server (Google Cloud MCP Server) 설치, 설정
    Google Cloud MCP Server 는 Google Cloud의 공식 제품은 없습니다.

    설치 Github docs : https://github.com/ergut/mcp-bigquery-server

    아래의 명령어를 통해 서버를 설치합니다.

    아래 3개 항목에 대해 확인을 합니다.
    SA json파일은 빈란으로 두어도 무방하며, 나머지 bigquery 위치와 GCP 프로젝트를 설정합니다.
    Optional path to your service account key JSON file (optional)
    BigQuery location (optional) us-central1
    Your Google Cloud project ID (required)

    SA키 사용이 아닌 사용자 계정으로 사용할 경우에는  “gcloud auth application-default login” 명령어를 통해 GCP 인증 하여 프로젝트로 접근 가능하도록 합니다.


  4. Gemini CLI 설정

    - 인증방법
    현재 인증방법으로는 아래와 같이 3가지가 있습니다.
    1) 개인 Google (Gmail)인증
    2) Gemini API (AI Studio) / GCP 프로젝트 빌링연결 필요, 학습내용 공유되는 퍼블릭
    3) Vertex AI (GCP의 AI 서비스) 로 구분됩니다.
    2025년 7월 기준 개인 Google으로도 충분하게 사용할 수 있으므로 Googlg 로그인 하여 인증 후 진행합니다.
    기업에서 사용시에는 학습내용이 공유되지 않는 Vertex AI로 하시기를 권장드립니다.

 

현재 Gemini CLI은 출시된지 얼마 안된 상태입니다. 하여 Claude Desktop설정하는 방안과 동일하게 진행합니다.

Gemini CLI 설정파일 위치 : /Users/사용자/.gemini/settings.json

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
-------------------------------------------------
위 쉼표 추가 후에 아래 mcp servers 부분부터 추가합니다.
{
  "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"
      ]
    }
  }
}

 

서비스키를 사용하지 않는다고 하면 (gcloud auth application-default login 사용) 아래와 같이 서비스키를 제외하고 작성합니다.
{
  "mcpServers": {
    "bigquery": {
      "command": "npx",
      "args": [
        "-y",
        "@ergut/mcp-bigquery-server",
        "--project-id",
        "your-project-id",
        "--location",
        "us-central1"
      ]
    }
  }
}
 
gemini CLI를 재실행 후 /mcp 를 입력합니다.

 



MCP서버의 리스트가 확인되며, 어떤 기능을 사용할 수 있는지도 확인할 수 있습니다.
이번에 사용한 MCP는 Bigquery 전용만 가능합니다

 

5. 사용방안

본 문서에서는 MCP서버가 자연어로 문의한 것을 이해 후 직접 “Bigquery”으로 조회하여 정리하는 방안을 테스트 했습니다.
향 후 MCP서버에 기능이 더 추가되고, 안정화 된다면 리소스 추가, 삭제, 수정이 가능할 것입니다.

아래와 같은 자연어로 조회를 하고 답변을 받았습니다.

1. 해당 프로젝트에 있는 빅쿼리 데이터가 무엇이 있는지 확인해줘
-> 해당 데이터 셋을 조회하여 반환해주었습니다.
2. 해당 데이터 셋에 테이블이 몇개 있는지 확인하고, 10개 이하면 5개씩 잘라서 보여줘
-> 테이블 1개만 조회가 완료되었고, 해당 테이블의 내용을 보여주었습니다.
3.  테이블 내용을 보고 몇개 있는지 확인해줘 그리고 10개 이하면 5개씩 잘라서 보여줘
-> 테이블의 전체 행 수를 확인 후 조건에 따라 테이블 내용을 보여주었습니다.

-text 예시
✦ 성공했습니다! test_dataset 데이터셋에 있는 테이블 리스트는 다음과 같습니다:

  테이블 이름: products

> 테이블 내용을 보고 몇개 있는지 확인해줘 그리고 10개 이하면 5개씩 잘라서 보여줘

✦ products 테이블의 전체 행 수를 먼저 확인하겠습니다.
 ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ✔  Shell bq query --location=US --project_id=ctu-gcp-dsa2-unit --use_legacy_sql=false "SELECT COUNT(*) FROM test_dataset.products"                    │
 │                                                                                                                                                       │
 │    +-----+                                                                                                                                            │
 │    | f0_ |                                                                                                                                            │
 │    +-----+                                                                                                                                            │
 │    |   3 |                                                                                                                                            │
 │    +-----+                                                                                                                                            │
 │                                                                                                                                                       │
 ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ products 테이블에는 총 3개의 행이 있습니다. 요청하신 대로 테이블 내용을 보여드리겠습니다.
 ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
 │ ✔  Shell bq query --location=US --project_id=ctu-gcp-dsa2-unit --use_legacy_sql=false "SELECT * FROM test_dataset.products"                           │
 │                                                                                                                                                       │
 │    +------------+--------------+--------+                                                                                                             │
 │    | product_id | product_name | price  |                                                                                                             │
 │    +------------+--------------+--------+                                                                                                             │
 │    | p003       | Keyboard     |  75.75 |                                                                                                             │
 │    | p001       | Laptop       | 1200.5 |                                                                                                             │
 │    | p002       | Mouse        |   25.0 |                                                                                                             │
 │    +------------+--------------+--------+                                                                                                             │
 │                                                                                                                                                       │
 ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ products 테이블의 내용은 다음과 같습니다. 총 3개의 행이 있습니다.



   1 +------------+--------------+--------+
   2 | product_id | product_name | price  |
   3 +------------+--------------+--------+
   4 | p003       | Keyboard     |  75.75 |
   5 | p001       | Laptop       | 1200.5 |
   6 | p002       | Mouse        |   25.0 |
   7 +------------+--------------+--------+

아래는 데이터 추가시 나오는 메시지 입니다.
자연어로만 설명했는데도 의도를 이해하고 데이터를 생성하려 했습니다.
지금은 지원되지 않지만 빠른시일내 추가될 것으로 예상됩니다.