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

이 문서에서는 AlloyDB 인스턴스를 모델 컨텍스트 프로토콜(MCP)을 지원하는 다양한 에이전트에 연결하는 방법을 설명합니다.

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

또는 MCP를 지원하는 다른 IDE 및 에이전트가 데이터베이스용 MCP 도구 상자를 통해 연결될 수 있습니다. 도구 상자는 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 인스턴스에 연결하려면 먼저 다음 단계를 완료하여 프로젝트와 데이터베이스를 설정합니다.

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.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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 role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. 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가 필요합니다.

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

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

참고: AlloyDB Gemini CLI 확장 프로그램은 데이터베이스용 MCP 도구 상자를 기반으로 합니다. 데이터베이스용 MCP 도구 상자는 현재 베타 버전(v1.0 이전)이며 첫 번째 안정화 출시 버전(v1.0)이 출시될 때까지 브레이킹 체인지가 발생할 수 있습니다.

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

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

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

다음 예시에서는 다음 테이블이 있는 샘플 ecommerce 데이터베이스를 사용합니다.

• products: product_id, product_name, category, price를 포함한 제품 정보가 포함됩니다.
• customers: customer_id, first_name, last_name, email과 같은 고객 데이터를 저장합니다.
• orders: order_id, customer_id, order_date를 포함한 주문 정보를 보유합니다.

카테고리	도구	자연어 프롬프트 예시
데이터베이스 작업	list_tables	현재 데이터베이스의 모든 테이블을 보여 줘.
	execute_sql	'노트북' 카테고리에서 가장 비싼 제품 10개를 보여 줘.
	list_active_queries	데이터베이스에서 실행 중인 쿼리는 무엇인가요?
	get_query_plan	지난 6개월 동안 주문을 하지 않은 모든 고객을 찾는 쿼리에 대한 쿼리 계획을 설명해 줘.
	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	참고: create_user 도구는 두 가지 유형의 데이터베이스 사용자를 만들 수 있습니다. 기본 제공 인증을 사용하는 데이터베이스 사용자: 이러한 사용자는 데이터베이스 내에서 관리되며 비밀번호로 인증합니다. IAM 사용자: 이러한 사용자는 IAM에서 관리되며 IAM 사용자 인증 정보로 인증합니다. 기본 제공 인증을 사용하여 데이터베이스 사용자를 만들 때는 비밀번호를 제공해야 합니다. IAM 사용자를 만들 때 IAM 주 구성원을 제공해야 합니다. 비밀번호가 report_password인 새 데이터베이스 사용자 reporting_user를 만들어 줘. [e-mail]의 새 IAM 데이터베이스 사용자를 만들어 줘.
	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	ecommerce 데이터베이스에서 잘못된 색인을 확인해 줘.

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 Code Assist에서 Gemini CLI를 사용하도록 구성하는 것이 좋습니다. 이 방법을 사용하면 MCP 서버를 수동으로 구성하지 않아도 됩니다.

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

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

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

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

IDE를 AlloyDB에 연결하려면 AI 에이전트를 데이터에 연결하는 오픈소스 서버인 데이터베이스용 MCP 도구 상자를 설치해야 합니다.

1. 도구 상자 최신 버전을 바이너리로 다운로드합니다. 운영체제(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"
      }
    }
  }
}

참고: 비공개 IP 주소를 사용하여 연결하려면 env 객체에 "ALLOYDB_POSTGRES_IP_TYPE": "private" 줄을 추가하세요.

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"
      }
    }
  }
}

참고: 비공개 IP 주소를 사용하여 연결하려면 env 객체에 "ALLOYDB_POSTGRES_IP_TYPE": "private" 줄을 추가하세요.

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

Cline

1. VS Code에서 Cline 확장 프로그램을 열고 MCP 서버 아이콘을 탭합니다.
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"
      }
    }
  }
}


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



참고: 비공개 IP 주소를 사용하여 연결하려면 env 객체에 "ALLOYDB_POSTGRES_IP_TYPE": "private" 줄을 추가하세요.

커서

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"
      }
    }
  }
}

참고: 비공개 IP 주소를 사용하여 연결하려면 env 객체에 "ALLOYDB_POSTGRES_IP_TYPE": "private" 줄을 추가하세요.

4. 커서를 열고 설정 > 커서 설정 > 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"
      }
    }
  }
}

참고: 비공개 IP 주소를 사용하여 연결하려면 env 객체에 "ALLOYDB_POSTGRES_IP_TYPE": "private" 줄을 추가하세요.

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"
      }
    }
  }
}

참고: 비공개 IP 주소를 사용하여 연결하려면 env 객체에 "ALLOYDB_POSTGRES_IP_TYPE": "private" 줄을 추가하세요.