K8s クラスタ運用 MCP Server

FastMCP ベースの Kubernetes 運用クエリ用 MCP サービス。kubectl get / describe / logs / events --watch などの日常的なトラブルシューティング操作を、LLM が呼び出せる読み取り専用ツールとしてカプセル化し、Claude などのクライアントが直接クラスタ状態を読み取り、障害の現場を特定できるようにします。

⚠️ 本プロジェクトは読み取り専用ツールのみを公開しています（create/update/delete なし）。ただし、後述の「セキュリティ推奨事項」に従い、読み取り専用 ServiceAccount の RBAC と組み合わせて使用することを推奨します。

ツール一覧

さらに、@mcp.prompt（ノード調査 / クラスタ巡回ガイド）と @mcp.resource（k8s://cluster/summary クラスタサマリー）の追加機能があります。

Related MCP server: k8s-readonly-mcp

ディレクトリ構造

├── 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（Pod 内の SA）→ 明示的な KUBECONFIG_PATH → 公式 kubeconfig 解決チェーン。単一の真実源であり、複数ファイルから合成しません。

MCP クライアントへの接続

Claude Code を例にします（HTTP トランスポートが 127.0.0.1:8081 で実行中の場合）：

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

セキュリティ推奨事項

1. 読み取り専用 RBAC を使用：本サービスを実行する Pod / ユーザーには読み取り専用の ClusterRole を設定し、高権限の資格情報を借用しないようにします。

2. デフォルトでローカルのみにバインド：MCP_HOST はデフォルトで 127.0.0.1。外部に公開する場合は、必ずリバースプロキシ層で認証（TLS + Token / OIDC）を追加してください。HTTP トランスポート自体には認証とレート制限がありません。

3. 証明書検証を無効にしない：K8S_VERIFY_SSL=false は自己署名証明書の一時的なデバッグのみに使用し、本番環境では true のままにしてください。

4. 認証情報をリポジトリに入れない：kubeconfig には秘密鍵が含まれます。.gitignore で kubeconfig* を除外済みです。強制的にコミットしないでください。

既知の制限

• すべてのツールは読み取り専用であり、変更操作は含まれません（これは意図的な設計です）。

• watch_* シリーズはグローバルな排他ロックに制限されます。同時に実行できる watch は 1 つのみで、API Server への負荷を避けます。

• イベント / ログ出力には長さ上限があります。巨大な内容は切り詰められます（read_pod_log の切り詰めロジックと query_events の max_count を参照）。