platform-mcp

Un servidor Model Context Protocol de solo lectura que convierte a un agente de IA (Claude Code, Claude Desktop o cualquier cliente MCP) en un ingeniero de plataforma de GCP. Apúntalo a tus proyectos de Google Cloud y pídele que investigue incidentes, haga inventario y detecte oportunidades de optimización de costos, todo sin ninguna capacidad de modificar tu infraestructura.

Solo observación. Ninguna herramienta de este servidor muta el estado. Combinado con una identidad de solo visor (más abajo), te brinda una garantía sólida de defensa en profundidad de que un agente puede mirar pero nunca tocar.

Qué puede hacer

Prompts típicos una vez conectado:

• "¿Cuáles son los principales grupos de errores en las últimas 24 horas y cuál es el más reciente?"

• "¿Qué grupos de nodos de GKE están sobreaprovisionados? Muestra la CPU media según el tipo de máquina."

• "¿Dónde puedo reducir gastos en este proyecto?"

Related MCP server: k8s-readonly-mcp

Múltiples entornos

Un servidor puede alcanzar varios proyectos. Defínelos en PLATFORM_MCP_ENVIRONMENTS (consulta Configuración) y el agente elegirá uno según la redacción de tu prompt:

• "¿Algún error en staging en la última hora?"

• "Compara los servicios de Cloud Run entre staging y prod."

Cada herramienta acepta un argumento opcional environment. Si se omite, se usa el entorno predeterminado; pasa environment="production" para apuntar a otro. Los nombres, cualquier alias que definas, abreviaturas comunes (prod, stg, qa, …) e identificadores de proyecto simples se resuelven. Un nombre no reconocido es un error que lista las opciones válidas: un error tipográfico nunca puede redirigir silenciosamente al proyecto equivocado.

Cada entorno tiene su propia cuenta de servicio, por lo que staging y producción se alcanzan mediante identidades separadas desde el mismo proceso, y cada resultado devuelve el environment y project del que proviene.

Requisitos

• Python 3.11+

• Un proyecto de Google Cloud y credenciales (tu propio inicio de sesión o una cuenta de servicio)

• La CLI de gcloud para la configuración inicial

Instalación

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

Configuración única de GCP

Ejecuta esto una vez por proyecto al que quieras acceder: staging y producción necesitan sus propias APIs habilitadas y su propia cuenta de servicio de solo lectura.

1. Habilita las APIs de las que dependen las herramientas:

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. Otorga acceso de solo lectura a la identidad con la que se ejecuta el servidor.

Para desarrollo local con tu propio inicio de sesión (Application Default Credentials):

gcloud auth application-default login

La identidad necesita estos roles de visor en el proyecto, además de roles/billing.viewer en la cuenta de facturación:

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. (Recomendado) Usa una cuenta de servicio dedicada de solo lectura en lugar de tu inicio de sesión:

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

Luego refiérela como el valor impersonate de ese entorno en PLATFORM_MCP_ENVIRONMENTS (preferido: sin archivo de clave), o apunta a una clave descargada mediante GOOGLE_APPLICATION_CREDENTIALS.

La suplantación la realiza la identidad a la que resuelve tu ADC. Si tu ADC es en sí misma una cuenta de servicio suplantada, esa SA (no tu usuario) necesita roles/iam.serviceAccountTokenCreator en cada platform-mcp-ro.

Modelo de seguridad

El modo de solo lectura se aplica mediante IAM, no mediante el alcance de OAuth. El servidor solicita el amplio alcance cloud-platform y permanece en solo lectura únicamente porque nunca llama a una API que mute el estado. No confíes solo en el código: ejecútalo bajo una identidad de solo visor (paso 3 anterior) para que la credencial en sí sea incapaz de escribir, sin importar qué código se ejecute. Esto te da dos capas independientes: el servidor no intenta escribir, y la identidad no podría aunque lo intentara.

Con múltiples entornos, esto se mantiene por proyecto: cada entorno se autentica como su propia cuenta de servicio, por lo que una identidad de staging nunca se usa para acceder a producción. Otorga a cada uno acceso de solo visor únicamente a su proyecto.

Configuración

Copia la configuración de ejemplo y completa tus valores:

cp .mcp.json.example .mcp.json

.mcp.json está en git-ignore, por lo que tus identificadores de proyecto y correos de cuentas de servicio permanecen locales. Variables de entorno que puede configurar (o tu shell):

PLATFORM_MCP_ENVIRONMENTS contiene un objeto JSON; cada entrada acepta:

Un valor de cadena simple es una abreviatura de {"project": "..."}. Como JSON dentro de .mcp.json, las comillas deben escaparse; sin escapar se lee:

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

Modo de entorno único. Si PLATFORM_MCP_ENVIRONMENTS no está configurado, el servidor se comporta como antes, exponiendo un entorno llamado default:

Registro con un cliente

Claude Code / Claude Desktop — agrega el bloque de .mcp.json.example a tu configuración de MCP (.mcp.json en un proyecto para Claude Code, o claude_desktop_config.json para Desktop), apuntando command al script de consola del venv para que no se necesite instalación global:

{
  "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 — para pruebas interactivas:

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

Notas

• Todas las herramientas limitan el número de resultados y truncan cargas útiles largas para ser amigables con los tokens.

• Los clientes de GCP se crean de forma diferida y se almacenan en caché por entorno, por lo que cambiar entre staging y producción a mitad de conversación cuesta una construcción de cliente por cada uno.

• Los recomendadores de costos son zonales/regionales; list_cost_recommendations descubre automáticamente las ubicaciones donde tienes recursos (mediante Asset Inventory) y se expande, omitiendo ubicaciones y recomendadores que están vacíos o no disponibles.

• get_cost_breakdown utiliza consultas parametrizadas de BigQuery con un conjunto de columnas de agrupación en lista blanca.

Licencia

MIT © 2026 Dimuthu Wickramanayake