platform-mcp

Только чтение Model Context Protocol сервер, который превращает AI-агента (Claude Code, Claude Desktop или любого MCP-клиента) в инженера платформы GCP. Укажите ему ваши проекты Google Cloud и попросите расследовать инциденты, провести инвентаризацию и выявить возможности оптимизации затрат — всё это без какой-либо возможности изменить вашу инфраструктуру.

Только наблюдение. Ни один инструмент в этом сервере не изменяет состояние. В сочетании с идентичностью только для просмотра (ниже) это даёт вам жёсткую гарантию защиты в глубину: агент может смотреть, но никогда не трогать.

Что он умеет

Типичные запросы после подключения:

• «Какие группы ошибок самые частые за последние 24 часа, и какая из них самая новая?»

• «Какие пулы узлов GKE избыточно обеспечены? Покажи среднее использование CPU по типу машины.»

• «Где я могу сократить расходы в этом проекте?»

Related MCP server: k8s-readonly-mcp

Несколько окружений

Один сервер может работать с несколькими проектами. Определите их в PLATFORM_MCP_ENVIRONMENTS (см. Конфигурация), и агент выберет нужное по формулировке вашего запроса:

• «Есть ли ошибки в staging за последний час?»

• «Сравни сервисы Cloud Run между staging и prod»

Каждый инструмент принимает необязательный аргумент environment. Если его опустить, используется окружение по умолчанию; передайте environment="production", чтобы обратиться к другому. Имена, любые заданные вами псевдонимы, распространённые сокращения (prod, stg, qa, …) и просто идентификаторы проектов — всё распознаётся. Неизвестное имя вызывает ошибку с перечислением допустимых вариантов — опечатка никогда не приведёт к тихому перенаправлению на неверный проект.

Каждое окружение использует собственный сервисный аккаунт, поэтому staging и production доступны через отдельные идентичности из одного процесса, и каждый результат возвращает environment и project, из которых он получен.

Требования

• Python 3.11+

• Проект Google Cloud и учётные данные (ваш собственный вход или сервисный аккаунт)

• CLI gcloud для разовой настройки

Установка

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

Разовая настройка GCP

Выполните эти шаги один раз для каждого проекта, к которому хотите получить доступ — для staging и production нужны свои включённые 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. Предоставьте доступ только для чтения идентичности, под которой работает сервер.

Для локальной разработки с вашим собственным входом (Application Default Credentials):

gcloud auth application-default login

Этой идентичности нужны следующие роли просмотра на проекте, плюс 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

Затем укажите его как значение impersonate для этого окружения в PLATFORM_MCP_ENVIRONMENTS (предпочтительно — без файла ключа) или укажите путь к скачанному ключу через GOOGLE_APPLICATION_CREDENTIALS.

Имперсонация выполняется той идентичностью, в которую разрешается ваш ADC. Если ваш ADC сам является имперсонализированным сервисным аккаунтом, то этому SA — а не вашему пользователю — нужна роль roles/iam.serviceAccountTokenCreator на каждом platform-mcp-ro.

Модель безопасности

Только чтение обеспечивается IAM, а не областью OAuth. Сервер запрашивает широкую область cloud-platform и остаётся только для чтения исключительно потому, что никогда не вызывает изменяющий API. Не полагайтесь только на код — запускайте его под идентичностью только для просмотра (шаг 3 выше), чтобы сами учётные данные были неспособны на запись, независимо от того, какой код выполняется. Это даёт два независимых уровня: сервер не пытается писать, а идентичность не смогла бы, даже если бы попыталась.

С несколькими окружениями это остаётся по-проектным: каждое окружение аутентифицируется как собственный сервисный аккаунт, поэтому идентичность staging никогда не используется для доступа к production. Предоставьте каждому доступ только для просмотра только к своему проекту.

Конфигурация

Скопируйте пример конфигурации и заполните свои значения:

cp .mcp.json.example .mcp.json

.mcp.json игнорируется git, поэтому ваши идентификаторы проектов и адреса сервисных аккаунтов остаются локальными. Переменные окружения, которые он (или ваша оболочка) может задать:

PLATFORM_MCP_ENVIRONMENTS содержит JSON-объект; каждая запись принимает:

Простое строковое значение — это сокращение для {"project": "..."}. Как JSON внутри .mcp.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-конфигурацию (.mcp.json в проекте для Claude Code, или claude_desktop_config.json для Desktop), указав 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-клиенты создаются лениво и кэшируются для каждого окружения, поэтому переключение между staging и production в середине разговора стоит одного создания клиента.

• Рекомендатели затрат являются зональными/региональными; list_cost_recommendations автоматически обнаруживает местоположения, где у вас есть ресурсы (через Asset Inventory), и рассылает запросы, пропуская пустые или недоступные местоположения и рекомендателей.

• get_cost_breakdown использует параметризованные запросы BigQuery с белым списком столбцов для группировки.

Лицензия

MIT © 2026 Dimuthu Wickramanayake