MCP Server для эксплуатации кластера K8s

MCP-сервис для эксплуатационных запросов Kubernetes на базе FastMCP. Оборачивает повседневные диагностические действия, такие как kubectl get / describe / logs / events --watch, в read-only инструменты, вызываемые LLM, позволяя клиентам вроде Claude напрямую читать состояние кластера и находить первопричину инцидента.

⚠️ Этот проект предоставляет только read-only инструменты (без create/update/delete). Тем не менее рекомендуется использовать его с RBAC на основе read-only ServiceAccount, см. раздел «Рекомендации по безопасности» ниже.

Список инструментов

Также есть две дополнительные возможности: @mcp.prompt (руководство по диагностике узлов / проверке кластера) и @mcp.resource (k8s://cluster/summary — сводка по кластеру).

Related MCP server: Kubernetes MCP Server

Структура каталога

├── app.py              # FastMCP 实例（叶子模块，破循环导入）
├── k8s_server.py       # 入口：导入 Tools 即自动注册全部工具
├── k8s_client.py       # K8s 客户端懒加载 + 单一配置真源
├── config.py           # 12-Factor 环境变量配置
├── prompts.py          # @mcp.prompt 引导
├── resources.py        # @mcp.resource 资源
├── Tools/              # 每个工具一个文件，导入即注册
├── utils/              # 纯解析/辅助模块（无 K8s/MCP 依赖）
└── tests/              # 单元测试

Установка и запуск

# 1. 创建虚拟环境并安装依赖
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

# 2. 运行（HTTP transport，默认 127.0.0.1:8081）
python k8s_server.py

Запуск тестов

pip install -r requirements-dev.txt
python -m pytest -q

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

Всё настраивается через переменные окружения, со значениями по умолчанию (см. config.py):

Приоритет загрузки конфигурации подключения к K8s: in-cluster (SA внутри Pod) → явный KUBECONFIG_PATH → официальная цепочка разрешения kubeconfig. Единый источник истины, без сборки из нескольких файлов.

Подключение MCP-клиента

На примере Claude Code (когда HTTP transport уже запущен на 127.0.0.1:8081):

{
  "mcpServers": {
    "k8s-node-server": {
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

Рекомендации по безопасности

1. Используйте read-only RBAC: настройте для Pod / пользователя, запускающего сервис, read-only ClusterRole, чтобы не использовать учётные данные с избыточными правами.

2. По умолчанию привязка только к локальной машине: MCP_HOST по умолчанию 127.0.0.1. Если нужно открыть доступ извне, обязательно добавьте аутентификацию на уровне reverse proxy (TLS + Token / OIDC), поскольку HTTP transport сам по себе не имеет аутентификации и ограничения частоты запросов.

3. Не отключайте проверку сертификатов: K8S_VERIFY_SSL=false используйте только для временной отладки самоподписанных сертификатов; в production оставляйте true.

4. Не храните учётные данные в репозитории: kubeconfig содержит секреты, .gitignore уже исключает kubeconfig*, не принуждайте к коммиту.

Известные ограничения

• Все инструменты — read-only, без операций изменения (это осознанное решение).

• Серия watch_* ограничена глобальной блокировкой конкурентности: в один момент времени может выполняться только один watch, чтобы не создавать нагрузку на API Server.

• Вывод событий/логов имеет ограничение по длине; слишком большие объёмы обрезаются (см. логику обрезки в read_pod_log и max_count в query_events).