MCP Tools Reference: cloudcli.googleapis.com

도구: run_gcloud_command

사용자의 Google Cloud 프로젝트 내에서 단일 gcloud CLI 명령어를 실행합니다. 심각한 안전 경고 (파괴적일 수 있음): 이 도구는 GCP 리소스 (예: gcloud compute instances delete)를 만들거나 업데이트하거나 삭제할 수 있습니다. 읽기 전용 명령어로 제한되지 않습니다. 매우 주의해서 사용하세요. 금지된 명령어: 에이전트는 다음 gcloud 명령어 (알파/베타 변형 포함)를 실행해서는 안 됩니다. app deploy, app instances ssh, auth, billing, components, config, docker, feedback, info, init, meta, survey. 엄격한 실행 규칙:

  1. 이 도구를 사용할 때는 'project' 매개변수 (예: project="projects/PROJECT_ID")를 제공해야 합니다 (Cloud CLI Execution API 사용 설정 확인, 결제, 할당량 등에 사용됨). 이는 gcloud가 작동하는 프로젝트를 지정하는 데 사용되는 gcloud 명령어의 --project 플래그와 동일하지 않습니다.
  2. 플래그 형식 지정: 모든 긴 옵션에 대해 항상 '=' 기호를 사용하여 플래그 키와 값을 구분해야 합니다. 올바른 예: --zone=us-central1-a 또는 --project=my-project. 잘못된 예: --zone us-central1-a 또는 --project my-project.
  3. 결제 프로젝트: 실행 환경에서 사전 구성된 프로젝트 또는 결제 설정을 가정할 수 없습니다. 프로젝트 범위가 지정되지 않은 명령어 (예: 폴더 또는 조직 수준) 또는 Cloud Storage 요청자 지불과 같은 특정 시나리오의 경우 --billing-project=PROJECT 플래그를 전달해야 합니다. 프로젝트 범위 명령어의 경우 리소스 프로젝트 재정의를 지원하지 않는 GCP API에 적용되는 할당량 프로젝트를 재정의하기 위해 --billing-project=PROJECT를 추가로 지정할 수 있습니다.
  4. 프로젝트 범위: 프로젝트 범위 명령어의 경우 항상 --project=PROJECT_ID 플래그를 전달해야 합니다. 조직 또는 폴더 수준 명령어에는 사용하지 마세요. 프로젝트 범위 명령어에 --project 플래그를 제공하지 않으면 리소스 프로젝트는 기본적으로 --billing-project 플래그에 설정된 프로젝트로 지정됩니다.
  5. gcloud 명령어에서 --billing-project 플래그를 지정하는 경우 값이 프로젝트 ID 또는 프로젝트 번호인지 확인합니다. 값은 특수 값 (예: LEGACY, CURRENT_PROJECT, CURRENT_PROJECT_WITH_FALLBACK)이 아니어야 합니다.
  6. 명령어 문자열에 --project 또는 --billing-project 중 하나 이상을 지정해야 합니다.
  7. 비동기 작업: 장기 실행 동기 작업 (예: VM 또는 데이터베이스 만들기)의 경우 에이전트 시간 초과를 방지하기 위해 항상 --async 플래그를 전달해야 합니다.
  8. 로그 비율 제한: gcloud logging read을 사용하는 경우 사용자 인증 정보 및 연결 시간 초과를 방지하기 위해 항상 --limit 플래그 (예: --limit=100)를 포함해야 합니다.
  9. 자가 수정: 명령어가 오류를 반환하면 stderr를 분석하고, 문법 또는 플래그를 수정하고, 다음 반복에서 다시 시도합니다.
  10. input_files: (선택사항) 명령어를 실행하기 전에 환경에서 만들 파일 목록입니다. 각 파일에는 '경로'(현재 디렉터리 기준)와 '콘텐츠'가 있어야 합니다. '콘텐츠'는 파일의 콘텐츠를 나타내는 일반 텍스트여야 합니다. 파일에서 읽는 명령어 (예: gcloud builds submit --config=cloudbuild.yaml --async --project=PROJECT_ID)에 유용합니다.

gcloud 명령어/패턴 예시:

  1. 심각도>=ERROR인 GCE 인스턴스 로그 읽기: gcloud logging read "severity>=ERROR AND resource.type='gce_instance'" --limit=10 --order=DESC --project=PROJECT_ID
    • 필터 표현식에 따옴표를 사용합니다.
  2. 모든 PSC 엔드포인트 나열: gcloud compute forwarding-rules list --project=PROJECT_ID
  3. PSC 엔드포인트 설명: gcloud compute forwarding-rules describe FORWARDING_RULE_NAME --region=REGION --project=PROJECT_ID
    • --region 플래그에 '='를 사용합니다.
  4. 모든 클러스터 나열: gcloud container clusters list --project=PROJECT_ID
  5. 클러스터 설명: gcloud container clusters describe CLUSTER_NAME --region=REGION --project=PROJECT_ID
  6. Compute 인스턴스 나열: gcloud compute instances list --project=PROJECT_ID
  7. 프로젝트의 IAM 정책 가져오기: gcloud projects get-iam-policy PROJECT_ID --project=PROJECT_ID

응답 문자열은 기본적으로 터미널 출력 (stdout 또는 stderr)용으로 형식이 지정됩니다. --format 플래그를 사용하여 형식을 변경합니다.

다음 샘플에서는 curl을 사용하여 run_gcloud_command MCP 도구를 호출하는 방법을 보여줍니다.

curl 요청 
                  
curl --location 'https://cloudcli.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "run_gcloud_command",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

입력 스키마

RunGcloud 요청 메시지입니다.

RunGcloudRequest

JSON 표현 
{
  "project": string,
  "command": string,
  "inputFiles": [
    {
      object (File)
    }
  ]
}
필드
project

string

필수 항목입니다. Cloud CLI Execution API의 API 사용 설정 및 할당량 소비를 위한 프로젝트입니다.

형식은 projects/ 또는 projects/
command

string

필수 항목입니다. 단일 문자열로 실행할 전체 gcloud 명령줄입니다. 예: "gcloud compute instances create my-vm --zone=us-central1-a"

LLM은 시간 초과를 방지하기 위해 장기 실행 작업에 --async 플래그를 사용하도록 안내됩니다.
inputFiles[]

object (File)

선택사항입니다. 실행을 위해 gcloud 명령어에 제공할 파일입니다.

파일

JSON 표현 
{
  "path": string,
  "contents": string
}
필드
path

string

필수 항목입니다. 홈 디렉터리를 기준으로 하는 파일 경로입니다. 상위 디렉터리 탐색 (..) 또는 셸 확장을 포함해서는 안 됩니다.
contents

string

필수 항목입니다. 파일의 콘텐츠입니다.

출력 스키마

RunGcloud 요청 메시지입니다.

RunGcloudResponse

JSON 표현 
{
  "response": {
    object (CliExecutionResponse)
  },
  "outputFiles": [
    {
      object (File)
    }
  ]
}
필드
response

object (CliExecutionResponse)

독립적인 stdout, stderr 스트림과 종료 코드를 포함하는 CLI 도구 실행의 응답입니다.
outputFiles[]

object (File)

실행에서 gcloud 명령어로 생성된 파일입니다.

CliExecutionResponse

JSON 표현 
{
  "stdout": string,
  "stderr": string,
  "exitCode": string
}
필드
stdout

string

CLI 도구 실행의 stdout 스트림입니다.
stderr

string

CLI 도구 실행의 stderr 스트림입니다.
exitCode

string (int64 format)

CLI 도구 실행의 종료 코드입니다.

파일

JSON 표현 
{
  "path": string,
  "contents": string
}
필드
path

string

필수 항목입니다. 홈 디렉터리를 기준으로 하는 파일 경로입니다. 상위 디렉터리 탐색 (..) 또는 셸 확장을 포함해서는 안 됩니다.
contents

string

필수 항목입니다. 파일의 콘텐츠입니다.

도구 주석

파괴적 힌트: ✅ | 멱등성 힌트: ❌ | 읽기 전용 힌트: ❌ | 오픈 월드 힌트: ❌