MCP 도구 상자를 사용하여 IDE를 AlloyDB에 연결

이 페이지에서는 데이터베이스용 MCP Toolbox를 사용하여 PostgreSQL용 AlloyDB 인스턴스를 Model Context Protocol (MCP)을 지원하는 통합 개발 환경 (IDE) 및 개발자 도구에 연결하는 방법을 보여줍니다. 이 도구를 사용하여 SQL 쿼리를 실행하고 데이터베이스와 상호작용합니다. 이 가이드는 기존 IDE 및 개발자 도구를 사용하여 AlloyDB로 작업하는 개발자를 위한 것입니다.

이 페이지에서는 AlloyDB 데이터베이스가 있고 AlloyDB 인스턴스에 공개 IP 주소가 있다고 가정합니다. 자세한 내용은 MCP 도구 상자로 AlloyDB 데이터베이스 만들기를 참고하세요.

Model Context Protocol (MCP)은 대규모 언어 모델 (LLM)을 AlloyDB와 같은 데이터 소스에 연결하기 위한 개방형 프로토콜입니다. 이 페이지에서는 데이터베이스용 MCP Toolbox를 사용하여 다음 IDE를 통해 개발자 지원 도구를 AlloyDB 인스턴스에 노출하는 방법을 설명합니다.

• Cursor
• Windsurf(Codium)
• Visual Studio Code(Copilot)
• Cline(VS Code 확장 프로그램)
• Claude desktop
• Claude code
• Gemini CLI
• Gemini Code Assist

시작하기 전에

필수 역할이 있는지 확인합니다.

필요한 역할

AlloyDB 인스턴스에 연결하려면 다음 역할 또는 이에 상응하는 Identity and Access Management (IAM) 권한이 필요합니다.

• Cloud AlloyDB 클라이언트 (roles/alloydb.client)
• 서비스 사용량 소비자(roles/serviceusage.serviceUsageConsumer)

데이터베이스 설정

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.

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.

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. PostgreSQL용 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. 클러스터 및 클러스터의 기본 인스턴스를 만들거나 선택합니다. MCP Toolbox는 AlloyDB 언어 커넥터를 사용하여 인스턴스에 안전하게 연결됩니다.
3. 환경에 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다.
4. 데이터베이스 사용자를 만들거나 재사용합니다. 사용자 이름과 비밀번호를 입력할 준비를 합니다.

MCP Toolbox 설치

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

   linux/amd64

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

   darwin/arm64

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

   darwin/amd64

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

   windows/amd64

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

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

   chmod +x toolbox
   

3. 설치를 확인합니다.

   ./toolbox --version
   

MCP 클라이언트 구성

Claude 코드

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

4. Claude Desktop을 다시 시작합니다.
5. 새 채팅 화면에 새 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"
      }
    }
  } 
}

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

Visual Studio Code(Copilot)

1. VS Code를 열고 프로젝트 루트에 .vscode 디렉터리가 없으면 만듭니다.
2. .vscode/mcp.json 파일이 없으면 만들고 엽니다.
3. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

{
 "mcp":{
    "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"
      }
    }
  }
}

Gemini CLI

1. Gemini CLI를 설치합니다.
2. 작업 디렉터리에 .gemini이라는 폴더를 만듭니다. 이 폴더 내에 settings.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"
      }
    }
  }
}

Gemini Code Assist

1. Visual Studio Code에 Gemini Code Assist 확장 프로그램을 설치합니다.
2. Gemini Code Assist 채팅에서 에이전트 모드를 사용 설정합니다.
3. 작업 디렉터리에 .gemini이라는 폴더를 만듭니다. 이 폴더 내에 settings.json 파일을 만듭니다.
4. 다음 구성을 추가하고 환경 변수를 값으로 바꾼 후 저장합니다.

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

AI 도구 사용

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

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

• list_tables: 테이블과 설명을 나열합니다.
• execute_sql: SQL 문을 실행합니다.
참고: 사전 빌드된 도구는 1.0 이전 버전이므로 버전 간에 도구 변경사항이 있을 수 있습니다. LLM은 사용 가능한 도구에 적응하므로 대부분의 사용자에게는 영향을 미치지 않습니다.