platform-mcp

A read-only Model Context Protocol server that turns an AI agent (Claude Code, Claude Desktop, or any MCP client) into a GCP platform engineer. Point it at a Google Cloud project and ask it to investigate incidents, take inventory, and surface cost-optimization opportunities — all without any ability to change your infrastructure.

Observation only. No tool in this server mutates state. Combined with a viewer-only identity (below), that gives you a hard, defense-in-depth guarantee that an agent can look but never touch.

What it can do

Typical prompts once it's connected:

• "What are the top error groups in the last 24 hours, and which one is newest?"

• "Which GKE node pools are over-provisioned? Show mean CPU against machine type."

• "Where can I reduce spend in this project?"

Requirements

• Python 3.11+

• A Google Cloud project and credentials (your own login, or a service account)

• The gcloud CLI for the one-time setup

Install

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

One-time GCP setup

1. Enable the APIs the tools depend on:

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. Grant read-only access to the identity the server runs as.

For local development with your own login (Application Default Credentials):

gcloud auth application-default login

The identity needs these viewer roles on the project, plus roles/billing.viewer on the billing account:

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. (Recommended) Use a dedicated read-only service account instead of your login:

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

Then impersonate it (preferred — no key file):

export IMPERSONATE_SERVICE_ACCOUNT=$SA

…or point at a downloaded key via GOOGLE_APPLICATION_CREDENTIALS.

Security model

Read-only is enforced by IAM, not by OAuth scope. The server requests the broad cloud-platform scope and stays read-only purely because it never calls a mutating API. Do not rely on the code alone — run it under a viewer-only identity (step 3 above) so the credential itself is incapable of writing, regardless of what code executes. This gives you two independent layers: the server doesn't try to write, and the identity couldn't if it did.

Configuration

Copy the example config and fill in your values:

cp .mcp.json.example .mcp.json

.mcp.json is git-ignored, so your project id and service-account email stay local. Environment variables it (or your shell) can set:

Register with a client

Claude Code / Claude Desktop — add the block from .mcp.json.example to your MCP config (.mcp.json in a project for Claude Code, or claude_desktop_config.json for Desktop), pointing command at the venv's console script so no global install is needed:

{
  "mcpServers": {
    "platform-mcp": {
      "command": "/absolute/path/to/platform-mcp/.venv/bin/platform-mcp",
      "env": {
        "GCP_PROJECT": "YOUR_PROJECT_ID",
        "IMPERSONATE_SERVICE_ACCOUNT": "platform-mcp-ro@YOUR_PROJECT_ID.iam.gserviceaccount.com"
      }
    }
  }
}

MCP Inspector — for interactive testing:

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

Notes

• All tools cap result counts and truncate long payloads to stay token-friendly.

• Cost recommenders are zonal/regional; list_cost_recommendations auto-discovers the locations where you have resources (via Asset Inventory) and fans out, skipping locations and recommenders that are empty or unavailable.

• get_cost_breakdown uses parameterized BigQuery queries with a whitelisted set of group-by columns.

License

MIT © 2026 Dimuthu Wickramanayake