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

이 문서에서는 AlloyDB 인스턴스를 Model Context Protocol (MCP)을 지원하는 다양한 에이전트에 연결하는 방법을 설명합니다.

Gemini CLI에는 전용 AlloyDB 확장 프로그램을 사용하는 것이 좋습니다. Gemini CLI는 기본 MCP 서버를 확장 프로그램에 직접 통합하므로 별도의 서버를 설정할 필요가 없습니다. Gemini CLI를 사용하도록 Gemini Code Assist를 구성하여 IDE에서 유사한 설정 이점을 누릴 수 있습니다.

또는 MCP를 지원하는 다른 IDE 및 에이전트가 데이터베이스용 MCP 도구 상자를 통해 연결할 수 있습니다. Toolbox는 AI 에이전트를 데이터에 연결하도록 설계된 오픈소스 MCP 서버입니다. 인증 및 연결 풀링과 같은 작업을 처리하므로 IDE에서 직접 자연어로 데이터와 상호작용할 수 있습니다.

시작하기 전에

AlloyDB 인스턴스에 연결하고 사용 가능한 도구를 사용하려면 다음 Identity and Access Management (IAM) 역할 중 하나 또는 이에 상응하는 권한이 있는 커스텀 역할이 있어야 합니다.

작업 역할 이름 필요한 Identity and Access Management (IAM) 역할
읽기 전용 도구를 사용하여 AlloyDB 리소스 나열 및 가져오기 AlloyDB 뷰어 roles/alloydb.viewer
인스턴스에 연결하고 쿼리 실행 Cloud AlloyDB 클라이언트 roles/alloydb.client
서비스 사용량 소비자 roles/serviceusage.serviceUsageConsumer
클러스터, 인스턴스, 사용자 만들기 또는 관리와 같은 관리 작업 실행 AlloyDB 관리자 roles/alloydb.admin
관측 가능성 확장 프로그램 사용 모니터링 뷰어 roles/monitoring.viewer

AlloyDB 인스턴스에 연결하려면 다음 단계를 완료하여 프로젝트와 데이터베이스를 설정하세요.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. AlloyDB를 만들고 여기에 연결하는 데 필요한 Cloud API를 사용 설정합니다.

    API 사용 설정

    1. 프로젝트 확인 단계에서 다음을 클릭하여 변경할 프로젝트의 이름을 확인합니다.

    2. API 사용 설정 단계에서 사용 설정을 클릭하여 다음을 사용 설정합니다.

      • AlloyDB API
      • Compute Engine API
      • Cloud Resource Manager API
      • Service Networking API

      AlloyDB와 동일한 Google Cloud 프로젝트에 있는 VPC 네트워크를 사용하여 AlloyDB에 대한 네트워크 연결을 구성하려면 Service Networking API가 필요합니다.

      다른 Google Cloud 프로젝트에 있는 VPC 네트워크를 사용하여 AlloyDB에 대한 네트워크 연결을 구성하려면 Compute Engine API와 Cloud Resource Manager API가 필요합니다.

  7. 클러스터 및 클러스터의 기본 인스턴스 만들기 또는 선택
  8. 환경에 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다.
  9. 데이터베이스 사용자를 만들거나 재사용합니다. 사용자 이름과 비밀번호를 입력할 준비를 합니다.

    10. AlloyDB용 Gemini CLI 확장 프로그램 사용

    Gemini CLI는 코딩, 디버깅, 데이터 탐색, 콘텐츠 제작을 지원하여 개발 워크플로를 지원하도록 설계된 오픈소스 AI 에이전트입니다. 이 도구의 목표는 Data Cloud 서비스 및 인기 있는 오픈소스 데이터베이스와 상호작용할 수 있는 에이전트 인터페이스를 제공하는 것입니다.

    Gemini CLI와의 통합은 표준 MCP 도구 상자 연결에 비해 추가 기능을 제공하는 전용 확장 프로그램을 통해 이루어집니다. 다음 섹션에서는 설치 프로세스와 도구 세트를 제공하는 alloydb 및 alloydb-observability 확장 프로그램을 설명합니다. 오픈소스 확장 프로그램에는 설치, 구성, 사용 예시에 관한 자세한 정보가 포함되어 있습니다. 자세한 내용은 Gemini CLI 확장 프로그램 - PostgreSQL용 AlloyDB를 참고하세요.

    alloydb 확장 프로그램에는 데이터베이스를 쿼리하고, AlloyDB 리소스를 관리하고, 데이터베이스 상태를 모니터링하는 도구가 포함되어 있습니다.

    카테고리 도구 자연어 프롬프트 예시
    데이터베이스 작업 list_tables 현재 데이터베이스의 모든 테이블을 보여 줘.
    execute_sql SELECT * FROM products WHERE category = 'electronics' 쿼리를 실행합니다.
    list_active_queries 데이터베이스에서 실행 중인 쿼리는 무엇인가요?
    get_query_plan 'SELECT * FROM customers WHERE last_seen > '2025-08-01''의 쿼리 계획을 설명해 줘.
    list_available_extensions 설치할 수 있는 확장 프로그램은 무엇인가요?
    list_installed_extensions 설치된 모든 확장 프로그램을 나열합니다.
    리소스 관리
    클러스터, 인스턴스, 사용자    		 create_cluster us-east1 리전에 sales-quarterly-db라는 AlloyDB 클러스터를 만듭니다.
    get_cluster sales-quarterly-db 클러스터의 세부정보를 가져옵니다.
    list_clusters 내 모든 AlloyDB 클러스터를 나열해 줘.
    create_instance sales-quarterly-db 클러스터에 새 읽기 인스턴스를 만듭니다.
    get_instance sales-quarterly-db-rp 인스턴스의 정보를 보여 줘.
    list_instances sales-quarterly-db 클러스터의 모든 인스턴스를 나열합니다.
    create_user reporting_user라는 새 데이터베이스 사용자를 만듭니다.
    get_user 사용자 reporting_user의 정보를 가져옵니다.
    list_users 모든 데이터베이스 사용자를 나열합니다.
    wait_for_operation operation-163562789 작업의 상태는 무엇인가요?
    데이터베이스 상태 및 유지관리 list_autovacuum_configurations 현재 autovacuum 구성을 보여 줘.
    list_memory_configurations 기본 인스턴스의 현재 메모리 구성은 무엇인가요?
    list_top_bloated_tables 가장 비대한 테이블 5개를 나열해 줘.
    list_replication_slots 활성 복제 슬롯을 모두 표시합니다.
    list_invalid_indexes orders 데이터베이스에서 잘못된 색인을 확인합니다.

    alloydb-observability 확장 프로그램은 Gemini CLI에서 직접 데이터베이스 성능과 상태를 관리하고 모니터링할 수 있는 통합 인터페이스를 제공합니다.

    카테고리 도구 자연어 프롬프트 예시
    관측 가능성 get_system_metrics 지난 한 시간 동안의 CPU 사용량과 같은 시스템 측정항목은 무엇인가요?
    get_query_metrics 지난 15분 동안의 쿼리 성능 측정항목을 보여 줘.

    AlloyDB용 Gemini CLI 확장 프로그램은 다음 두 가지 방법으로 사용할 수 있습니다.

    • 독립형 명령줄 도구
    • Gemini Code Assist와 함께 IDE에 통합

    Gemini CLI

    1. Gemini CLI를 설치합니다.
    2. 다음 명령어를 사용하여 GitHub 저장소에서 Gemini CLI용 AlloyDB 확장 프로그램을 설치합니다. 
      gemini extensions install https://github.com/gemini-cli-extensions/alloydb
    3. AlloyDB 인스턴스에 연결하도록 환경 변수를 설정합니다. 
      export ALLOYDB_POSTGRES_PROJECT="PROJECT_ID"
export ALLOYDB_POSTGRES_REGION="REGION"
export ALLOYDB_POSTGRES_CLUSTER="CLUSTER_NAME"
export ALLOYDB_POSTGRES_INSTANCE="INSTANCE_NAME"
export ALLOYDB_POSTGRES_DATABASE="DATABASE_NAME"

      AlloyDB용 Gemini CLI 확장 프로그램은 기본적으로 인증에 [애플리케이션 기본 사용자 인증 정보 (ADC)](/authentication/application-default-credentials)를 사용합니다. 대신 데이터베이스 사용자로 연결하려면 다음 선택적 환경 변수를 설정하세요.

      #Optional: Set for database user authentication
export ALLOYDB_POSTGRES_USER="USERNAME"
export ALLOYDB_POSTGRES_PASSWORD="PASSWORD"

      비공개 IP 주소를 사용하여 연결하려면 다음 환경 변수도 설정해야 합니다.

      export ALLOYDB_POSTGRES_IP_TYPE="private"
    4. 대화형 모드에서 Gemini CLI를 시작합니다. 
      gemini
      CLI는 Gemini CLI용 AlloyDB 확장 프로그램과 도구를 자동으로 로드하므로 이를 사용하여 데이터베이스와 상호작용할 수 있습니다.

    Gemini Code Assist

    Gemini CLI를 사용하도록 Gemini Code Assist를 구성하는 것이 좋습니다. 이 방법을 사용하면 MCP 서버를 수동으로 구성할 필요가 없습니다.

    1. Gemini CLI와 alloydb 확장 프로그램이 설치되고 구성되어 있는지 확인합니다.
    2. Gemini CLI를 사용하도록 Gemini Code Assist 구성
    3. Gemini Code Assist 채팅 내에서 직접 자연어를 사용하여 AlloyDB 인스턴스와 상호작용합니다.

    데이터베이스용 MCP 도구 상자를 사용하여 다른 IDE와 연결

    이 섹션에서는 데이터베이스용 MCP Toolbox를 사용하여 다양한 에이전트에서 AlloyDB 인스턴스에 연결하는 방법을 설명합니다. 도구 상자는 IDE와 데이터베이스 사이에 있는 오픈소스 모델 컨텍스트 프로토콜 (MCP) 서버 역할을 하며 AI 도구를 위한 컨트롤 플레인을 제공합니다. 이 섹션에서는 공개 또는 비공개 IP 주소를 사용하여 AlloyDB 인스턴스에 연결하는 방법을 설명합니다. 기본적으로 Toolbox는 공개 IP 주소를 사용하지만 구성 예에 표시된 대로 ALLOYDB_POSTGRES_IP_TYPE 환경 변수를 설정하여 비공개 IP 연결을 구성할 수 있습니다.

    데이터베이스용 MCP 도구 상자 설치

    IDE를 AlloyDB에 연결하려면 AI 에이전트를 데이터에 연결하는 오픈소스 서버인 MCP Toolbox for Databases를 설치해야 합니다.

    1. 최신 버전의 Toolbox를 바이너리로 다운로드합니다. 운영체제(OS) 및 CPU 아키텍처에 해당하는 바이너리를 선택합니다. 도구 상자 버전 v0.15.0 이상을 사용해야 합니다.

      linux/amd64

      curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/linux/amd64/toolbox

      darwin/arm64

      curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/arm64/toolbox

      darwin/amd64

      curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/darwin/amd64/toolbox

      windows/amd64

      curl -O https://storage.googleapis.com/genai-toolbox/v0.15.0/windows/amd64/toolbox

    2. 바이너리를 실행 파일로 만듭니다.

      chmod +x toolbox

    3. 설치를 확인합니다.

      ./toolbox --version

    클라이언트 구성

    다음 옵션 중에서 에이전트 도구를 선택합니다.

    Claude code

    1. Claude Code를 설치합니다.
    2. 프로젝트 루트에 .mcp.json 파일이 없으면 이 파일을 만듭니다.
    3. 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

    Claude Desktop

    1. Claude Desktop을 열고 설정으로 이동합니다.
    2. 개발자 탭에서 구성 수정을 클릭하여 구성 파일을 엽니다.
    3. 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
    1. Claude Desktop을 다시 시작합니다.
    2. 새 채팅 화면에 새 MCP 서버와 함께 망치(MCP) 아이콘이 표시됩니다.

    Cline

    1. VS Code에서 Cline 확장 프로그램을 열고 MCP Servers 아이콘을 탭합니다.
    2. MCP 서버 구성을 클릭하여 구성 파일을 엽니다.
    3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

    {
  "mcpServers": {
    "alloydb": {
     "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

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

    커서

    1. 프로젝트 루트에 .cursor 디렉터리가 없으면 이 디렉터리를 만듭니다.
    2. .cursor/mcp.json 파일이 없으면 만들고 엽니다.
    3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}
    1. 커서를 열고 설정 > 커서 설정 > MCP로 이동합니다. 서버가 연결되면 녹색 활성 상태가 표시됩니다.

    Visual Studio Code(Copilot)

    1. VS Code를 열고 프로젝트 루트에 .vscode 디렉터리가 없으면 만듭니다.
    2. .vscode/mcp.json 파일이 없으면 만들고 엽니다.
    3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
    {
  "servers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
        "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
        "ALLOYDB_POSTGRES_REGION": "REGION",
        "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
        "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
        "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
        "ALLOYDB_POSTGRES_USER": "USERNAME",
        "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}

    Windsurf

    1. Windsurf를 열고 Cascade 어시스턴트로 이동합니다.
    2. MCP 아이콘을 클릭한 다음 구성을 클릭하여 구성 파일을 엽니다.
    3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.
    {
  "mcpServers": {
    "alloydb": {
      "command": "./PATH/TO/toolbox",
      "args": ["--prebuilt","alloydb-postgres","--stdio"],
      "env": {
          "ALLOYDB_POSTGRES_PROJECT": "PROJECT_ID",
          "ALLOYDB_POSTGRES_REGION": "REGION",
          "ALLOYDB_POSTGRES_CLUSTER": "CLUSTER_NAME",
          "ALLOYDB_POSTGRES_INSTANCE": "INSTANCE_NAME",
          "ALLOYDB_POSTGRES_DATABASE": "DATABASE_NAME",
          "ALLOYDB_POSTGRES_USER": "USERNAME",
          "ALLOYDB_POSTGRES_PASSWORD": "PASSWORD"
      }
    }
  }
}