platform-mcp

읽기 전용 Model Context Protocol 서버로, AI 에이전트(Claude Code, Claude Desktop 또는 모든 MCP 클라이언트)를 GCP 플랫폼 엔지니어로 전환합니다. Google Cloud 프로젝트를 가리키고 인시던트 조사, 인벤토리 수집, 비용 최적화 기회 파악을 요청하세요. 인프라를 변경할 수 있는 능력은 전혀 없습니다.

관찰 전용. 이 서버의 어떤 도구도 상태를 변경하지 않습니다. 아래의 뷰어 전용 ID와 결합하면 에이전트가 볼 수는 있어도 절대 건드릴 수 없다는 강력한 심층 방어 보장을 얻을 수 있습니다.

할 수 있는 일

연결 후 일반적인 프롬프트 예시:

• "지난 24시간 동안 상위 오류 그룹은 무엇이며, 가장 최신 것은 무엇인가요?"

• "어떤 GKE 노드 풀이 과도하게 프로비저닝되어 있나요? 머신 유형별 평균 CPU를 보여주세요."

• "이 프로젝트에서 지출을 줄일 수 있는 곳은 어디인가요?"

Related MCP server: k8s-readonly-mcp

여러 환경

하나의 서버로 여러 프로젝트에 접근할 수 있습니다. PLATFORM_MCP_ENVIRONMENTS 아래에 정의하고( 구성 참조), 에이전트는 프롬프트의 표현에서 하나를 선택합니다:

• *"지난 1시간 동안 스테이징에서 오류가 있나요?"*

• *"스테이징과 프로덕션 간 Cloud Run 서비스를 비교해 주세요."*

모든 도구는 선택적 environment 인수를 받습니다. 생략하면 기본 환경이 사용되고, environment="production"을 전달하면 다른 환경을 대상으로 합니다. 이름, 정의한 별칭, 일반적인 약어(prod, stg, qa 등) 및 프로젝트 ID가 모두 해석됩니다. 인식되지 않는 이름은 유효한 옵션을 나열하는 오류가 됩니다. 오타가 잘못된 프로젝트를 조용히 다시 대상으로 삼을 수 없습니다.

각 환경은 자체 서비스 계정을 가지므로 스테이징과 프로덕션은 동일한 프로세스에서 별도의 ID로 접근되며, 모든 결과는 출처가 된 environment와 project를 다시 에코합니다.

요구 사항

• Python 3.11+

• Google Cloud 프로젝트 및 자격 증명(자체 로그인 또는 서비스 계정)

• 일회성 설정을 위한 gcloud CLI

설치

git clone https://github.com/deBilla/platform-mcp.git
cd platform-mcp
python3 -m venv .venv
./.venv/bin/pip install -e .

일회성 GCP 설정

도달하려는 프로젝트별로 한 번씩 실행하세요. 스테이징과 프로덕션은 각각 자체 API를 활성화하고 자체 읽기 전용 서비스 계정이 필요합니다.

1. 도구가 의존하는 API를 활성화합니다:

gcloud services enable \
  logging.googleapis.com monitoring.googleapis.com clouderrorreporting.googleapis.com \
  recommender.googleapis.com cloudasset.googleapis.com cloudbilling.googleapis.com \
  bigquery.googleapis.com \
  --project YOUR_PROJECT_ID

2. 서버가 실행되는 ID에 읽기 전용 액세스를 부여합니다.

자체 로그인(Application Default Credentials)을 사용한 로컬 개발의 경우:

gcloud auth application-default login

ID는 프로젝트에 대해 다음 뷰어 역할이 필요하며, 결제 계정에 대해 roles/billing.viewer가 필요합니다:

roles/viewer                # broad read (compute, run, gke, sql via Asset Inventory)
roles/logging.viewer
roles/monitoring.viewer
roles/errorreporting.viewer
roles/recommender.viewer
roles/cloudasset.viewer
roles/bigquery.dataViewer    # only for get_cost_breakdown
roles/bigquery.jobUser       # only for get_cost_breakdown

3. (권장) 로그인 대신 전용 읽기 전용 서비스 계정을 사용합니다:

PROJECT=YOUR_PROJECT_ID
gcloud iam service-accounts create platform-mcp-ro \
  --display-name "platform-mcp read-only" --project $PROJECT

SA=platform-mcp-ro@$PROJECT.iam.gserviceaccount.com
for ROLE in roles/viewer roles/logging.viewer roles/monitoring.viewer \
  roles/errorreporting.viewer roles/recommender.viewer roles/cloudasset.viewer; do
  gcloud projects add-iam-policy-binding $PROJECT \
    --member="serviceAccount:$SA" --role="$ROLE"
done

# Let your own login impersonate it (no key file to manage):
gcloud iam service-accounts add-iam-policy-binding $SA \
  --member="user:you@example.com" \
  --role="roles/iam.serviceAccountTokenCreator" --project $PROJECT

그런 다음 PLATFORM_MCP_ENVIRONMENTS에서 해당 환경의 impersonate 값으로 참조하거나(키 파일 불필요 — 권장), GOOGLE_APPLICATION_CREDENTIALS를 통해 다운로드한 키를 가리킵니다.

가장은 ADC가 해석하는 ID에 의해 수행됩니다. ADC 자체가 가장된 서비스 계정인 경우, 해당 SA(사용자가 아님)가 각 platform-mcp-ro에 대해 roles/iam.serviceAccountTokenCreator가 필요합니다.

보안 모델

읽기 전용은 OAuth 범위가 아닌 IAM에 의해 적용됩니다. 서버는 광범위한 cloud-platform 범위를 요청하고, 변형 API를 호출하지 않기 때문에 순전히 읽기 전용으로 유지됩니다. 코드만으로 의존하지 마십시오 — 뷰어 전용 ID(위 3단계)로 실행하여 자격 증명 자체가 어떤 코드가 실행되든 쓰기가 불가능하도록 하십시오. 이렇게 하면 두 개의 독립적인 계층이 제공됩니다: 서버는 쓰기를 시도하지 않고, ID는 시도해도 쓸 수 없습니다.

여러 환경에서도 프로젝트별로 유지됩니다: 각 환경은 자체 서비스 계정으로 인증하므로 스테이징 ID가 프로덕션에 도달하는 데 사용되지 않습니다. 각각에 해당 프로젝트에만 뷰어 전용 액세스를 부여하십시오.

구성

예제 구성을 복사하고 값을 입력하세요:

cp .mcp.json.example .mcp.json

.mcp.json은 git-ignored이므로 프로젝트 ID와 서비스 계정 이메일이 로컬에 유지됩니다. (또는 셸)이 설정할 수 있는 환경 변수:

PLATFORM_MCP_ENVIRONMENTS는 JSON 객체를 보유하며, 각 항목은 다음을 허용합니다:

문자열 값은 {"project": "..."}의 약어입니다. .mcp.json 내부의 JSON으로서 따옴표는 이스케이프되어야 합니다. 이스케이프되지 않은 상태는 다음과 같습니다:

{
  "staging": {
    "project": "my-app-staging",
    "impersonate": "platform-mcp-ro@my-app-staging.iam.gserviceaccount.com"
  },
  "production": {
    "project": "my-app",
    "impersonate": "platform-mcp-ro@my-app.iam.gserviceaccount.com",
    "billing_export_table": "my-app.billing.gcp_billing_export_v1_XXXXXX"
  }
}

단일 환경 모드. PLATFORM_MCP_ENVIRONMENTS가 설정되지 않은 경우 서버는 이전처럼 동작하며 default라는 하나의 환경을 노출합니다:

클라이언트에 등록

Claude Code / Claude Desktop — .mcp.json.example의 블록을 MCP 구성(Claude Code의 경우 프로젝트의 .mcp.json, Desktop의 경우 claude_desktop_config.json)에 추가하고, command를 venv의 콘솔 스크립트로 지정하여 전역 설치가 필요 없도록 합니다:

{
  "mcpServers": {
    "platform-mcp": {
      "command": "/absolute/path/to/platform-mcp/.venv/bin/platform-mcp",
      "env": {
        "PLATFORM_MCP_DEFAULT_ENVIRONMENT": "staging",
        "PLATFORM_MCP_ENVIRONMENTS": "{\"staging\":{\"project\":\"YOUR_STAGING_PROJECT_ID\",\"impersonate\":\"platform-mcp-ro@YOUR_STAGING_PROJECT_ID.iam.gserviceaccount.com\"},\"production\":{\"project\":\"YOUR_PROD_PROJECT_ID\",\"impersonate\":\"platform-mcp-ro@YOUR_PROD_PROJECT_ID.iam.gserviceaccount.com\"}}"
      }
    }
  }
}

MCP Inspector — 대화형 테스트용:

./.venv/bin/mcp dev src/platform_mcp/server.py

참고 사항

• 모든 도구는 결과 수를 제한하고 긴 페이로드를 잘라 토큰 친화적으로 유지합니다.

• GCP 클라이언트는 지연 생성되고 환경별로 캐시되므로 대화 중 스테이징과 프로덕션을 전환해도 클라이언트 구성이 각각 한 번만 발생합니다.

• 비용 추천자는 영역/지역별입니다. list_cost_recommendations는 Asset Inventory를 통해 리소스가 있는 위치를 자동으로 발견하고 팬아웃하여 비어 있거나 사용할 수 없는 위치와 추천자를 건너뜁니다.

• get_cost_breakdown은 허용된 group-by 열 집합이 있는 매개변수화된 BigQuery 쿼리를 사용합니다.

라이선스

MIT © 2026 Dimuthu Wickramanayake