mcp-kubernetes

mcp-kubernetes

mcp-kubernetes は、AI アシスタントが Kubernetes クラスターを操作できるようにする Model Context Protocol（MCP）サーバーです。Claude、Cursor、GitHub Copilot などの AI ツールと Kubernetes の橋渡し役となり、自然言語でのリクエストを Kubernetes 操作に変換し、AI ツールが理解できる形式で結果を返します。

AI ツールでは、次のことができます。

• Kubernetes リソースをクエリする
• kubectl コマンドを実行する
• 自然言語でのやり取りを通じて Kubernetes クラスターを管理する
• Kubernetes リソースの状態を診断して解釈する

仕組み

インストール方法

コンテナーイメージの作成とサポートは終了しました。リリース済みのバイナリをローカルにインストールし、MCP クライアントが stdio サブプロセスとして実行するように設定してください。

ローカル

# For Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# For MacOS
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Claude Desktop、Cursor、ChatGPT Copilot、Github Copilot およびその他の対応 AI クライアントで MCP サーバーを設定します。例：

{
  "mcpServers": {
    "kubernetes": {
      "command": "<path of binary 'mcp-kubernetes'>",
      "args": ["--transport", "stdio"],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

オプション

環境変数：

• KUBECONFIG：kubeconfig ファイルへのパスです。例：/home/<username>/.kube/config。
• USE_LEGACY_TOOLS：統合された call_kubectl ツールの代わりに、複数の専用 kubectl ツールを使用するには true に設定します（デフォルト：false）。

コマンドライン引数：

Usage of ./mcp-kubernetes:
      --access-level string       Access level (readonly, readwrite, or admin) (default "readonly")
      --additional-tools string   Comma-separated list of additional tools to support (kubectl is always enabled). Available: helm,cilium,hubble
      --allow-namespaces string   Comma-separated list of namespaces to allow (empty means all allowed)
      --otlp-endpoint string      OTLP endpoint for OpenTelemetry traces (e.g. localhost:4317, default "")
      --timeout int               Timeout for command execution in seconds, default is 60s (default 60)
      --transport string          Transport mechanism to use (stdio only) (default "stdio")

統合ツールとレガシーツール

デフォルトでは、mcp-kubernetes はすべての kubectl 操作を単一のツールインターフェースに統合した、1 つの call_kubectl ツールを使用します。これにより、すべての機能を維持したまま、コンテキストの消費量を大幅に削減できます。

複数の専用ツール（6～7 個の個別ツール）を使うレガシーモードを使用するには、環境変数を設定します。

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "env": {
        "USE_LEGACY_TOOLS": "true"
      }
    }
  }
}

アクセスレベル

--access-level フラグで、許可する操作を制御します。

• readonly（デフォルト）：読み取り操作のみ許可されます（get、describe、logs など）。
• readwrite：読み取りと書き込みの操作が許可されます（create、delete、apply など）。
• admin：管理者操作（cordon、drain、taint など）を含むすべての操作が許可されます。

アクセスレベルに基づいて、登録時にツールと操作がフィルタリングされます。そのため、AI アシスタントには実際に使用できる操作のみが表示されます。

設定例：

// Read-only access (default)
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes"
    }
  }
}

// Read-write access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "readwrite"]
    }
  }
}

// Admin access
{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--access-level", "admin"]
    }
  }
}

使い方

AI クライアントで Kubernetes クラスターについて質問してください。MCP ツールを使うと、AI アシスタントが kubectl 操作を理解して使用しやすくなります。

質問の例

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

Show me all deployments in the production namespace

Scale my web deployment to 5 replicas

Check if I have permission to create pods

What is my current kubectl context?

List all available kubectl contexts

Switch to the production context

利用可能なツール

統合ツール（デフォルト）

デフォルトでは、mcp-kubernetes はすべての kubectl 操作を処理する、1 つの統合 call_kubectl ツールを使用します。この方法では、従来の複数ツールを使う方法と比較して、コンテキストの消費量を大幅に削減できます。

call_kubectl - kubectl コマンドを実行します

• 利用可能なアクセスレベル：すべて（操作はアクセスレベルに応じてフィルタリングされます）
• パラメーター：
  • command：実行する kubectl コマンド全体です。kubectl のプレフィックスを含めます（例：「kubectl get pods -n default」、「kubectl apply -f deployment.yaml」）。
• 例：

  # Get pods
  command: "kubectl get pods -n default"
  
  # Apply configuration
  command: "kubectl apply -f deployment.yaml"
  
  # Scale deployment
  command: "kubectl scale deployment nginx --replicas=3"
  

レガシーツール（オプション）

USE_LEGACY_TOOLS=true の場合、mcp-kubernetes サーバーは関連する操作をまとめた複数の専用 kubectl ツールを提供します。ツールはアクセスレベルに応じて自動的にフィルタリングされます。

Kubectl ツール

# Get all pods
operation: "get"
resource: "pods"
args: "--all-namespaces"

# Apply a configuration
operation: "apply"
resource: ""
args: "-f deployment.yaml"

# Drain a node (admin only)
operation: "drain"
resource: "node"
args: "worker-1 --ignore-daemonsets"

# Add a taint (admin only)
operation: "taint"
resource: "nodes"
args: "worker-1 key=value:NoSchedule"

# Scale a deployment
operation: "scale"
resource: "deployment"
args: "nginx --replicas=3"

# Check rollout status
operation: "rollout"
resource: "status"
args: "deployment/nginx"

# Add a label
operation: "label"
resource: "pods"
args: "nginx-pod app=web"

# Set image
operation: "set"
resource: "image"
args: "deployment/nginx nginx=nginx:latest"

# View logs
operation: "logs"
resource: ""
args: "nginx-pod -f"

# Execute command in pod
operation: "exec"
resource: ""
args: "nginx-pod -- ls /app"

# Get cluster info
operation: "cluster-info"
resource: ""
args: ""

# Explain pod spec
operation: "explain"
resource: "pod.spec"
args: "--recursive"

# Check permissions
operation: "auth"
resource: "can-i"
args: "create pods"

# Approve certificate
operation: "certificate"
resource: "approve"
args: "csr-name"

# Get current context
operation: "config"
resource: "current-context"
args: ""

# List all contexts
operation: "config"
resource: "get-contexts"
args: ""

# Switch context (readwrite/admin only)
operation: "config"
resource: "use-context"
args: "my-cluster-context"

command: "list --all-namespaces"

command: "status"

command: "status"
command: "observe observe --namespace backend-jobs  --from-label 'app=web'"
command: "list nodes"

テレメトリ

テレメトリの収集はデフォルトで有効です。

オプトアウトするには、環境変数 KUBERNETES_MCP_COLLECT_TELEMETRY=false を設定します。

OpenTelemetry のサポート

mcp-kubernetes サーバーは、OpenTelemetry Protocol（OTLP）を使用したテレメトリデータのエクスポートに対応しています。OTLP エンドポイントを設定すると、トレースを任意の OpenTelemetry 互換バックエンドに送信できます。

{
  "mcpServers": {
    "kubernetes": {
      "command": "mcp-kubernetes",
      "args": ["--otlp-endpoint", "localhost:4317"]
    }
  }
}

開発

MCP サーバーのリクエストとレスポンスを調べる方法：

npx @modelcontextprotocol/inspector <path of binary 'mcp-kubernetes'>

コントリビューション

このプロジェクトでは、コントリビューションと提案を歓迎します。ほとんどのコントリビューションでは、コントリビューターライセンス契約（CLA）への同意が必要です。この契約では、コントリビューションを使用する権利を付与する権限があり、実際にその権利を付与することを宣言します。詳細については、https://cla.opensource.microsoft.com をご覧ください。

プルリクエストを送信すると、CLA ボットが CLA の提出が必要かどうかを自動的に判定し、適切な方法（ステータスチェック、コメントなど）で PR に表示します。ボットの指示に従ってください。CLA を採用しているすべてのリポジトリを通じて、この手続きが必要なのは一度だけです。

このプロジェクトでは、Microsoft オープンソース行動規範を採用しています。詳細については、行動規範に関する FAQをご覧いただくか、ご質問やご意見がございましたら [email protected] までお問い合わせください。

商標

このプロジェクトには、プロジェクト、製品、またはサービスの商標やロゴが含まれている場合があります。Microsoft の商標やロゴを許可を得て使用する場合は、Microsoft の商標およびブランドガイドラインに従う必要があります。このプロジェクトを変更したバージョンで Microsoft の商標やロゴを使用する場合、混乱を招いたり、Microsoft が後援していると誤解させたりしてはなりません。サードパーティの商標やロゴを使用する場合は、各サードパーティのポリシーに従ってください。