MKP - Model Kontext Protocol Server for Kubernetes

MKP - Kubernetes 向け Model Kontext Protocol サーバー

MKP は、LLM を活用するアプリケーションが Kubernetes クラスターとやり取りできるようにする、Kubernetes 向けの Model Context Protocol（MCP）サーバーです。MCP プロトコルを通じて、Kubernetes リソースの一覧表示と適用を行うツールを提供します。

特長

• Kubernetes API サーバーがサポートするリソースを一覧表示
• クラスターリソースを一覧表示
• 名前空間リソースを一覧表示
• リソースとそのサブリソース（ステータス、スケール、ログなど）を取得
• クラスターリソースを適用（作成または更新）
• 名前空間リソースを適用（作成または更新）
• タイムアウト制御付きでポッド内のコマンドを実行
• API Machinery の非構造化クライアントを使用した、汎用的でプラグイン可能な実装
• 過剰な API 呼び出しを防ぐレート制限機能を内蔵

MKP を選ぶ理由

MKP は、Kubernetes 向け Model Context Protocol サーバーとして、いくつかの重要な利点を備えています。

Go によるネイティブ実装

• Kubernetes 自体と同じ言語で構築
• サーバーアプリケーションで優れたパフォーマンスを発揮
• 強力な型安全性と並行処理をサポート
• Kubernetes ライブラリとシームレスに統合

API との直接統合

• 外部依存関係なしで Kubernetes API machinery を直接使用
• kubectl、helm、その他の CLI ツールに依存しない
• Kubernetes API サーバーと直接通信
• オーバーヘッドを削減し、信頼性を向上

あらゆるリソースをサポート

• 非構造化クライアントを通じて、あらゆる Kubernetes リソースタイプに対応
• ハードコードされたリソーススキーマや専用ハンドラーが不要
• カスタムリソース定義（CRD）を自動的にサポート
• 新しい Kubernetes リソースにも対応できる設計

ミニマルな設計

• Kubernetes リソースの主要な操作に特化
• 関心事を明確に分離した、クリーンで保守しやすいコードベース
• 依存関係を最小限に抑えた軽量設計
• 理解、拡張、貢献が容易

本番環境に対応したアーキテクチャ

• 本番環境での信頼性とパフォーマンスを考慮して設計
• 適切なエラー処理とリソース管理
• 過剰な API 呼び出しを防ぐレート制限機能を内蔵
• 包括的な単体テストを備えた、テスト可能な設計
• Kubernetes 開発のベストプラクティスに準拠

前提条件

• Go 1.24 以降
• Kubernetes クラスターと kubeconfig
• タスクの実行に必要な Task

インストール

1. リポジトリをクローンします。

   git clone https://github.com/StacklokLabs/mkp.git
   cd mkp
   

2. 依存関係をインストールします。

   task install
   

3. サーバーをビルドします。

   task build
   

使用方法

サーバーの実行

デフォルトの kubeconfig でサーバーを実行するには：

task run

特定の kubeconfig でサーバーを実行するには：

KUBECONFIG=/path/to/kubeconfig task run-with-kubeconfig

特定のポートでサーバーを実行するには：

MCP_PORT=9091 task run

ToolHive で実行

MKP は ToolHive を使用して Model Context Protocol（MCP）サーバーとして実行できます。ToolHive を使うと、MCP サーバーのデプロイと管理を簡素化できます。

ToolHive の UI、CLI、または Kubernetes オペレーターを使って MKP をセットアップする詳しい手順については、 ToolHive のドキュメントを参照してください。

MCP ツール

MKP サーバーは、次の MCP ツールを提供します。

get_resource

Kubernetes リソースまたはそのサブリソースを取得します。

パラメーター：

• resource_type（必須）：取得するリソースの種類（クラスタースコープまたは名前空間スコープ）
• group：API グループ（例：apps、networking.k8s.io）
• version（必須）：API バージョン（例：v1、v1beta1）
• resource（必須）：リソース名（例：deployments、services）
• namespace：名前空間（名前空間スコープのリソースでは必須）
• name（必須）：取得するリソースの名前
• subresource：取得するサブリソース（例：status、scale、logs）
• parameters：リクエストのオプションパラメーター（以下の例を参照）

例：

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "name": "nginx-deployment",
    "subresource": "status"
  }
}

パラメーターを指定して、特定のコンテナーのログを取得する例：

{
  "name": "get_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "logs",
    "parameters": {
      "container": "my-container",
      "sinceSeconds": "3600",
      "timestamps": "true",
      "limitBytes": "102400"
    }
  }
}

Pod ログで利用できるパラメーター：

• container：ログを取得するコンテナーを指定します
• previous：前のコンテナーインスタンスのログを取得します（true/false）
• sinceSeconds：相対時間（秒）を指定し、その時間より新しいログのみを返します
• sinceTime：指定した時刻以降のログのみを返します（RFC3339 形式）
• timestamps：各行にタイムスタンプを含めます（true/false）
• limitBytes：返す最大バイト数
• tailLines：ログ末尾から返す行数

LLM のコンテキストウィンドウが大量のログで圧迫されないよう、Pod ログはデフォルトで直近 100 行、32KB に制限されています。上記のパラメーターでこれらのデフォルト値を変更できます。

通常のリソースで利用できるパラメーター：

• resourceVersion：指定すると、そのバージョン時点のリソースを表示します

list_resources

特定の種類の Kubernetes リソースを一覧表示します。

パラメーター：

• resource_type（必須）：一覧表示するリソースの種類（クラスタースコープまたは名前空間スコープ）
• group：API グループ（例：apps、networking.k8s.io）
• version（必須）：API バージョン（例：v1、v1beta1）
• resource（必須）：リソース名（例：deployments、services）
• namespace：名前空間（名前空間スコープのリソースでは必須）
• label_selector：リソースを絞り込むための Kubernetes ラベルセレクター（省略可）
• include_annotations：出力にアノテーションを含めるかどうか（デフォルト： true）
• exclude_annotation_keys：出力から除外するアノテーションキーのリスト （* によるワイルドカードに対応）
• include_annotation_keys：出力に含めるアノテーションキーのリスト（指定した場合は、 これらのみが含まれます）

アノテーションのフィルタリング

list_resources ツールでは、メタデータの出力サイズを制御し、大きなアノテーション（GPU ノードのアノテーションなど）による切り捨てを防ぐための、高度なアノテーションフィルタリング機能を利用できます。

基本的な使い方：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default"
  }
}

特定のアノテーションを除外する（GPU ノードで便利）：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "clustered",
    "group": "",
    "version": "v1",
    "resource": "nodes",
    "exclude_annotation_keys": [
      "nvidia.com/*",
      "kubectl.kubernetes.io/last-applied-configuration"
    ]
  }
}

特定のアノテーションのみを含める：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotation_keys": ["app", "version", "prometheus.io/scrape"]
  }
}

パフォーマンスを最大限に高めるため、アノテーションを完全に無効にする：

{
  "name": "list_resources",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "include_annotations": false
  }
}

アノテーションのフィルタリングルール：

• 大きな設定データが出力されないよう、デフォルトでは kubectl.kubernetes.io/last-applied-configuration が除外されます
• exclude_annotation_keys は * を使ったワイルドカードパターンに対応しています（例： nvidia.com/* は NVIDIA のアノテーションをすべて除外します）
• include_annotation_keys を指定すると、これが優先され、指定したアノテーションのみが含まれます
• include_annotations: false を設定すると、出力からすべてのアノテーションが完全に削除されます
• ワイルドカードパターンで * を使用できるのはキーの末尾のみです（例： nvidia.com/*）

apply_resource

Kubernetes リソースを適用（作成または更新）します。

パラメーター：

• resource_type（必須）：適用するリソースの種類（クラスタースコープまたは 名前空間スコープ）
• group：API グループ（例：apps、networking.k8s.io）
• version（必須）：API バージョン（例：v1、v1beta1）
• resource（必須）：リソース名（例：deployments、services）
• namespace：名前空間（名前空間スコープのリソースでは必須）
• manifest（必須）：リソースマニフェスト

例：

{
  "name": "apply_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "apps",
    "version": "v1",
    "resource": "deployments",
    "namespace": "default",
    "manifest": {
      "apiVersion": "apps/v1",
      "kind": "Deployment",
      "metadata": {
        "name": "nginx-deployment",
        "namespace": "default"
      },
      "spec": {
        "replicas": 3,
        "selector": {
          "matchLabels": {
            "app": "nginx"
          }
        },
        "template": {
          "metadata": {
            "labels": {
              "app": "nginx"
            }
          },
          "spec": {
            "containers": [
              {
                "name": "nginx",
                "image": "nginx:latest",
                "ports": [
                  {
                    "containerPort": 80
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

post_resource

Kubernetes リソースまたはそのサブリソースに POST します。特に、ポッド内でのコマンド実行に便利です。

パラメーター：

• resource_type（必須）：POST 先のリソースの種類（クラスタースコープまたは名前空間スコープ）
• group：API グループ（例：apps、networking.k8s.io）
• version（必須）：API バージョン（例：v1、v1beta1）
• resource（必須）：リソース名（例：deployments、services）
• namespace：名前空間スコープのリソースで必須となる名前空間
• name（必須）：POST 先のリソース名
• subresource：POST 先のサブリソース（例：exec）
• body（必須）：リソースに POST する本文
• parameters：リクエストのオプションパラメーター

ポッド内でコマンドを実行する例：

{
  "name": "post_resource",
  "arguments": {
    "resource_type": "namespaced",
    "group": "",
    "version": "v1",
    "resource": "pods",
    "namespace": "default",
    "name": "my-pod",
    "subresource": "exec",
    "body": {
      "command": ["ls", "-la", "/"],
      "container": "my-container",
      "timeout": 30
    }
  }
}

ポッドの exec に対する body では、次のフィールドをサポートしています。

• command（必須）：実行するコマンド。文字列または文字列の配列で指定します
• container（任意）：コマンドを実行するコンテナー名（デフォルトは最初のコンテナーです）
• timeout（任意）：タイムアウト時間（秒）（デフォルトは 15 秒、最大 60 秒です）

タイムアウトに関する注意：

• デフォルトのタイムアウト：指定しない場合は 15 秒です
• 最大タイムアウト：60 秒です（これを超える値は 60 秒に制限されます）
• タイムアウトを超過したコマンドは終了され、タイムアウトエラーが返されます

応答には stdout、stderr、およびエラーメッセージが含まれます。

{
  "apiVersion": "v1",
  "kind": "Pod",
  "metadata": {
    "name": "my-pod",
    "namespace": "default"
  },
  "spec": {
    "command": ["ls", "-la", "/"]
  },
  "status": {
    "stdout": "total 48\ndrwxr-xr-x   1 root root 4096 May  5 14:30 .\ndrwxr-xr-x   1 root root 4096 May  5 14:30 ..\n...",
    "stderr": "",
    "error": ""
  }
}

MCP リソース

MKP サーバーは、MCP リソースを通じて Kubernetes リソースへのアクセスを提供します。 リソース URI は次の形式です。

• クラスタースコープのリソース：k8s://clustered/{group}/{version}/{resource}/{name}
• 名前空間スコープのリソース： k8s://namespaced/{namespace}/{group}/{version}/{resource}/{name}

設定

トランスポートプロトコル

MKP は、MCP サーバー用に次の 2 つのトランスポートプロトコルをサポートしています。

• Streamable HTTP：デフォルトのトランスポートプロトコルで、ほとんどのユースケースに適しています
• SSE（Server-Sent Events）：レガシーなトランスポートプロトコルで、主に古いクライアントとの互換性のために使用されます

CLI フラグまたは環境変数を使用して、トランスポートプロトコルを設定できます。

# Using CLI flag
./build/mkp-server --transport=sse

# Using environment variable
MCP_TRANSPORT=sse ./build/mkp-server

# Default (Streamable HTTP)
./build/mkp-server

MKP を ToolHive の環境で実行すると、MCP_TRANSPORT 環境変数が ToolHive によって自動的に設定されます。

リソース検出の制御

デフォルトでは、MKP はすべての Kubernetes リソースを MCP リソースとして提供し、LLM に有用なコンテキストを提供します。ただし、多数のリソースを含む大規模なクラスターでは、LLM のコンテキスト領域を大幅に消費する可能性があります。

--serve-resources フラグを使用すると、この動作を無効にできます。

# Run without serving cluster resources
./build/mkp-server --serve-resources=false

# Run with a specific kubeconfig without serving cluster resources
./build/mkp-server --kubeconfig=/path/to/kubeconfig --serve-resources=false

リソース検出を無効にしても、MCP ツール（get_resource、list_resources、apply_resource、delete_resource、post_resource）は引き続き完全に機能するため、Kubernetes クラスターとやり取りできます。

書き込み操作の有効化

デフォルトでは、MKP は読み取り専用モードで動作します。つまり、クラスターへの書き込み操作は許可されず、apply_resource、delete_resource、post_resource ツールは利用できません。--read-write フラグを使用すると、書き込み操作を有効にできます。

# Run with write operations enabled
./build/mkp-server --read-write=true

# Run with a specific kubeconfig and write operations enabled
./build/mkp-server --kubeconfig=/path/to/kubeconfig --read-write=true

レート制限

MKP には、過剰な API 呼び出しからサーバーを保護する組み込みのレート制限機能があります。AI エージェントで使用する場合、これは特に重要です。 レートリミッターはトークンバケットアルゴリズムを使用し、操作の種類に応じて異なる制限を適用します。

• 読み取り操作（list_resources、get_resource）：1 分あたり 120 リクエスト
• 書き込み操作（apply_resource、delete_resource）：1 分あたり 30 リクエスト
• その他の操作のデフォルト：1 分あたり 60 リクエスト

レート制限はクライアントセッションごとに適用され、複数のクライアント間で公平にリソースが割り当てられます。レート制限機能は、コマンドラインフラグで有効または無効にできます。

# Run with rate limiting enabled (default)
./build/mkp-server

# Run with rate limiting disabled
./build/mkp-server --enable-rate-limiting=false

環境変数を使用して、レート制限をカスタマイズできます。

• MKP_RATE_LIMIT_DEFAULT：デフォルトのレート制限（デフォルト：60）
• MKP_RATE_LIMIT_READ：読み取り操作のレート制限（デフォルト：120）
• MKP_RATE_LIMIT_WRITE：書き込み操作のレート制限（デフォルト：30）

# Run with custom rate limits
MKP_RATE_LIMIT_READ=200 MKP_RATE_LIMIT_WRITE=50 ./build/mkp-server

開発

テストの実行

task test

コードのフォーマット

task fmt

コードのリンティング

task lint

依存関係の更新

task deps

コントリビューション

この MCP サーバーへのコントリビューションを歓迎します！コントリビューションを希望される場合は、 コントリビューションガイドをご確認ください。開始方法の詳細が記載されています。

バグを見つけた場合や機能のリクエストがある場合は、リポジトリで issue を作成するか、 コミュニティの Discord サーバーの #mcp-servers チャンネルにご参加ください。

ライセンス

このプロジェクトは Apache v2 License の下でライセンスされています。詳細については、 LICENSE ファイルをご覧ください。