kubectl-mcp

Сервер MCP (Model Context Protocol), который позволяет ИИ-агентам инспектировать кластеры Kubernetes на простом английском — спросите "какие поды перезапускались за последний час?" и получите реальный ответ.

Создано Терезой Тран.

Зачем

LLM-ассистенты отлично объясняют команды kubectl и ужасно справляются с их безопасным выполнением. kubectl-mcp предоставляет инспекцию кластера в режиме только для чтения как набор MCP-инструментов, которые агент может вызывать — превращая «проверь мой кластер» из копипасты с надеждой в настоящий диалог.

• Только чтение по дизайну. Никаких apply, delete или exec. Сервер только инспектирует.

• Режим моков по умолчанию. Поставляется с предзаполненным фейковым кластером, так что вы можете попробовать его за 30 секунд без реального кластера.

• Реальный режим, когда готовы. Укажите ваш KUBECONFIG — и он запросит живой кластер через официальный Python-клиент Kubernetes.

Related MCP server: mcp-k8s-context-server

Установка

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

Или из исходников:

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

Запуск в автономном режиме (проверка работоспособности)

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

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

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (mac) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

Для режима реального кластера:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Перезапустите Claude Desktop. Теперь вы можете спросить "перечисли поды в namespace production" и получить реальный ответ.

Другие MCP-совместимые клиенты

Любой клиент, поддерживающий stdio MCP (Cursor, Cline, Continue, кастомные агенты), работает так же — укажите ему на бинарник kubectl-mcp.

Доступные инструменты

Каждый инструмент имеет JSON Schema — LLM получают корректную валидацию аргументов бесплатно.

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

Переменные окружения:

Мок-кластер

Мок-кластер по умолчанию поставляется в src/kubectl_mcp/mock_data.json и включает:

• 3 namespace: default, production, staging

• ~15 подов в состояниях healthy, crashlooping и недавно перезапущенных

• Деплойменты, сервисы и поток недавних событий

• Некоторые поды имеют количество перезапусков > 0, так что find_restarted_pods возвращает реальные результаты

Вы можете переопределить его, установив KUBECTL_MCP_MOCK_DATA=/path/to/your.json, если хотите продемонстрировать конкретный сценарий.

Заметки по дизайну

• Только чтение по построению. Протокол KubernetesBackend определяет только методы чтения. Нет пути кода, который мог бы изменить состояние кластера — даже в реальном режиме.

• Бэкенд заменяемый. MockBackend и RealBackend реализуют один и тот же протокол. Добавление третьего (например, кэшированного снимка) — это один файл.

• Ошибки — это исключения, а не тихие null. ResourceNotFound, NamespaceNotFound и т.д. распространяются как McpError с полезными сообщениями, чтобы агент мог скорректировать курс.

• Транспорт stdio. Все вызовы MCP-инструментов — это JSON-RPC через stdio, точно соответствующий спецификации MCP.

Разработка

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

Планы

• Мок-бэкенд с предзаполненными данными

• Реальный бэкенд через Python-клиент kubernetes

• Поверхность инструментов только для чтения

• Автономный режим --demo для CI/смоук-тестов

• Поддержка нескольких кластеров (флаг --context)

• Инструменты метрик (CPU/память через metrics.k8s.io)

• Опциональный слой кэширования для частых запросов

Лицензия

MIT © 2026 Teresa Tran