kubernetes-mcp

Kubernetes MCP

English | 中文

Go で構築された、Kubernetes に特化した Model Context Protocol（MCP）サーバーです。 Kubernetes の操作を MCP ツールとして公開し、stdio、sse、streamable の各トランスポートをサポートします。

このプロジェクトの目的

• Kubernetes 操作のための統一された MCP インターフェース
• ローカルの kubeconfig とクラスター内構成の両方に対応
• さまざまな連携モードに対応する複数のトランスポート
• 汎用リソースの CRUD + ユーティリティツール + プロンプト + メトリクス
• レベル/フォーマットを設定可能な slog ベースのロギング

要件

• Go 1.24+
• Kubernetes クラスターへのアクセス
  • --kubeconfig 経由、または
  • クラスター内のサービスアカウント経由

クイックスタート

ビルド

git clone https://github.com/HSn0918/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp ./cmd/kubernetes-mcp

実行（stdio）

./kubernetes-mcp server transport stdio --kubeconfig ~/.kube/config

実行（SSE）

./kubernetes-mcp server transport sse \
  --port 8080 \
  --health-port 8081 \
  --allow-origins "*" \
  --base-url "http://localhost:8080" \
  --kubeconfig ~/.kube/config

実行（StreamableHTTP）

./kubernetes-mcp server transport streamable \
  --port 8080 \
  --health-port 8081 \
  --allow-origins "*" \
  --kubeconfig ~/.kube/config

CLI 構造

kubernetes-mcp
├── server
│   └── transport
│       ├── stdio
│       ├── sse
│       └── streamable
└── version

設定フラグ

グローバルフラグ：

• --log-level（debug|info|warn|error、デフォルト info）
• --log-format（console|json、デフォルト console）
• --kubeconfig（任意）

ネットワークトランスポートフラグ（sse、streamable）：

• --port（デフォルト 8080）
• --health-port（デフォルト 8081）
• --allow-origins（デフォルト *）

SSE 専用フラグ：

• --base-url（デフォルト http://localhost:<port>）

トランスポートエンドポイント

• StreamableHTTP MCP エンドポイント：POST /mcp
• ヘルスエンドポイント（SSE/Streamable のみ）：
  • GET /healthz
  • GET /readyz

ツールの概要

1. 汎用リソース操作

各 API グループプレフィックスに対して、サーバーは以下を公開します：

• LIST_<PREFIX>_RESOURCES
• GET_<PREFIX>_RESOURCE
• DESCRIBE_<PREFIX>_RESOURCE
• CREATE_<PREFIX>_RESOURCE
• UPDATE_<PREFIX>_RESOURCE
• DELETE_<PREFIX>_RESOURCE

登録済みプレフィックス：

• K8S

2. コア/クラスターユーティリティ

• LIST_NAMESPACES
• LIST_NODES
• GET_POD_LOGS
• ANALYZE_POD_LOGS

3. ユーティリティツール

• GET_CURRENT_TIME
• GET_CLUSTER_INFO
• GET_API_RESOURCES
• SEARCH_RESOURCES
• EXPLAIN_RESOURCE
• APPLY_MANIFEST
• VALIDATE_MANIFEST
• DIFF_MANIFEST
• GET_EVENTS

4. プロンプトツール

• KUBERNETES_YAML_PROMPT
• KUBERNETES_QUERY_PROMPT
• TROUBLESHOOT_PODS_PROMPT
• TROUBLESHOOT_NODES_PROMPT
• TROUBLESHOOT_NETWORK_PROMPT

5. メトリクスツール

• GET_NODE_METRICS
• GET_POD_METRICS
• GET_RESOURCE_METRICS
• GET_TOP_CONSUMERS

アーキテクチャ（k8s 形式の group/version）

cmd/kubernetes-mcp/
  main.go
  app/
pkg/
  client/kubernetes/
  config/
  handlers/
    apis/
      core/v1/
      apps/v1/
    base/
    tool/
    prompt/
    metrics/
  server/
  health/
  logger/

Docker

ビルド：

docker build -t kubernetes-mcp:latest .

明示的なトランスポートコマンドで実行：

docker run --rm -it \
  -v ~/.kube:/root/.kube \
  kubernetes-mcp:latest \
  server transport stdio --kubeconfig /root/.kube/config

Kubernetes へのデプロイ

デプロイ用マニフェストは /deploy/kubernetes にあります。

make k8s-deploy
# or
make k8s-deploy-kustomize

開発

make build
make test

Justfile + ワンクリックスキルインストール

このリポジトリには、プロジェクト利用スキルが skills/kubernetes-mcp-usage に含まれています。

# list just tasks
just

# common dev tasks
just build
just test

# install the project skill into Codex
just skill-install

# overwrite existing install
just skill-install-force

スキルのインストール先： $CODEX_HOME/skills/kubernetes-mcp-usage（CODEX_HOME が設定されていない場合は ~/.codex/skills/kubernetes-mcp-usage）。

インストール後、スキルを反映するために Codex を再起動してください。

注意事項

• リソース操作は、クラスターの API の可用性と RBAC 権限に依存します。
• ingress/リバースプロキシの背後でネットワークトランスポートを使用する場合、SSE のために --base-url を正しく設定してください。