K8stools

🚀 Kubernetes Tools

このパッケージは、エージェントが使用するためのKubernetes関数のコレクションを提供します。これらの関数は、エージェントに直接ツールとして渡すことも、MCPサーバー（含まれています）の背後に配置することもできます。いくつかの使用例を以下に示します。

• GitHub CoPilotやCursorを通じてKubernetesクラスターとチャットする。
• エージェントを構築して、クラスターを監視したり根本原因分析を行ったりする。
• カスタムチャットUIをコーディングする。
• エージェント以外の自動化で使用する。

✨ 主な機能

方法論

私たちの目標は、量よりも質に焦点を当てることです。つまり、十分にドキュメント化され、型が厳密に定義されたツールを提供することです。これは、エージェントが単なるデモ以上の効果的なツールの使用を可能にするために重要であると考えています。

これらのツールは、Kubernetes Python API（https://github.com/kubernetes-client/python）の上に構築されています。ここで提供されるツールには3つのスタイルがあります。

1. kubectlコマンドの出力を模倣するツールがあります（例：get_pod_summariesはkubectl get podsに相当します）。これらのツールの戻り値には、型が厳密に定義されたPydanticモデルが使用されています。
2. 関連するKubernetesクライアントタイプに一致しようとする、型が厳密に定義されたPydanticモデルを返すツールがあります（https://github.com/kubernetes-client/python/tree/master/kubernetes/docs を参照）。これらのモデルからは、あまり使用されないフィールドが省略される場合があります。この例としてget_pod_container_statusesがあります。
3. 場合によっては、APIが返すクラスに対してto_dict()を呼び出すだけです（https://github.com/kubernetes-client/python/tree/master/kubernetes/client/models で定義）。戻り値の型はdict[str,Any]ですが、関数のドキュメント文字列にフィールドが記載されています。get_pod_specはこのタイプのツールの例です。

現在の優先事項は、クラスターの状態を変更しない関数です。まずは監視 / RCAの使用例に焦点を当てたいと考えています。他の使用例に対応するツールを追加する際には、読み取り専用のツールとは別に管理するため、「安全な」エージェントを構築することができます。

📦 インストール

Via pip

pip install k8stools

Via uv

uv add k8stools

💻 使用例

基本的な使用法

エージェントで直接使用する

コアツールはk8stools.k8s_toolsにあります。以下はエージェントでの使用例です。

from pydantic_ai.agent import Agent
from k8stools.k8s_tools import TOOLS

agent = Agent(
        model="openai:gpt-4.1",
        system_prompt=SYSTEM_PROMPT,
        tools=TOOLS
)

result = agent.run_sync("What is the status of the pods in my cluster?")
print(result.output)

MCPを介して使用する

k8s-mcp-serverスクリプトは、同じセットのツールに対するMCPサーバーを提供します。以下はサーバーのコマンドライン引数です。

usage: k8s-mcp-server [-h] [--transport {streamable-http,stdio}] [--host HOST] [--port PORT]
                      [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--debug]

Run the MCP server.

options:
  -h, --help            show this help message and exit
  --transport {streamable-http,stdio}
                        Transport to use for MCP server [default: stdio]
  --host HOST           Hostname for HTTP service [default: 127.0.0.1]
  --port PORT           Port for HTTP service [default: 8000]
  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        Log level [default: INFO]
  --debug               Enable debug mode [default: False]

stdioトランスポートでMCPを使用する

stdioトランスポートは、GitHub CoPilotやCursorのようなローカルのコーディングエージェントでの使用に最適です。これはデフォルトの設定であるため、引数なしでk8s-mcp-serverスクリプトを実行できます。以下はmcp.jsonの設定例です。

{
   "servers": {
      "k8stools-stdio": {
         "command": "${workspaceFolder}/.venv/bin/k8s-mcp-server",
         "args": [
         ],
         "envFile": "${workspaceFolder}/.envrc"
      }
   }
}

これは以下のことを前提としています。

1. Python仮想環境は、VSCodeワークスペースのルートの.venvにあることが想定されています。
2. ワークスペースにk8stoolsパッケージがインストールされていること。
3. 環境ファイル.envrcに必要な変数が定義されています。特に、KUBECONFIGをkubectlの設定ファイルを指すように設定する必要がある場合があります。

streamable HTTPトランスポートでMCPを使用する

streamable httpトランスポートは、コマンドラインオプション--transport=streamable-httpで有効になります。指定されたアドレスとポート（それぞれデフォルトで127.0.0.1と8000）でリッスンするHTTPサーバーが起動します。このトランスポートは、MCPサーバーにリモートアクセスしたい場合に最適です。

以下は、サーバーを起動し、curlを使用してツール情報を取得する健全性テストを行う短い例です。

# start the server
 $ k8s-mcp-server --transport=streamable-http
[07/21/25 19:55:13] INFO     Starting with 6 tools on transport streamable-http           mcp_server.py:59
INFO:     Started server process [6649]
INFO:     Waiting for application startup.
INFO     StreamableHTTP session manager started         streamable_http_manager.py:111
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

# Now, open another terminal window and test it
$ curl -v \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{
           "jsonrpc": "2.0",
           "id": 1,
           "method": "tools/list",
           "params": {}
         }' \
     http://127.0.0.1:8000/mcp
*   Trying 127.0.0.1:8000...
* Connected to 127.0.0.1 (127.0.0.1) port 8000
> POST /mcp HTTP/1.1
> Host: 127.0.0.1:8000
> User-Agent: curl/8.7.1
> Content-Type: application/json
> Accept: application/json, text/event-stream
> Content-Length: 120
>
* upload completely sent off: 120 bytes
< HTTP/1.1 200 OK
< date: Tue, 22 Jul 2025 02:56:25 GMT
< server: uvicorn
< cache-control: no-cache, no-transform
< connection: keep-alive
< content-type: text/event-stream
< x-accel-buffering: no
< Transfer-Encoding: chunked
<
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"tools":[.... long text elided ...]}}

モックツール

エージェントを構築する際には、実際のクラスターにアクセスせずに、静的（しかし現実的）な値を返すモックバージョンを使用してテストすると便利です。k8stools.mock_toolsモジュールはその役割を果たします。データ値は、Open Telemetry Demoアプリケーションを実行している実際のMinikubeインスタンスに対して実行したときに取得されました。MCPサーバーを実行する際には、--mockコマンドラインオプションを使用してこれを有効にすることができます。

インストラクションファイル

GitHub CoPilotは、CoPilotコーディングエージェントに追加のコンテキストを提供できるインストラクションファイルをサポートしています。CoPilotはプロジェクトを分析して自動的に作成することもできます。デフォルトでは、これは.github/copilot-instructions.mdに保存されます。手動でインストラクションを追加することで、MCPツールを使用するエージェントをカスタマイズすることができます。例として、このリポジトリのcopilot-instructions.mdに含まれる追加の内容を以下に示します。

MCP Integration

Run server: k8s-mcp-server [--transport stdio|streamable-http] Tools auto-registered via Tool.from_function() in mcp_server.py

When answering questions about the user's kubernetes cluster, use the tools provided by this server, which is configured in mcp.json as k8stools-stdio. Some other considerations when answering these questions:

• If the answer includes multiple, similar entries, format as a table if possible.
• When providing pod statuses, be sure to include the state of the pod.
• When providing a status, use an icon show quickly show if it is good or bad.
• If you are asked for the current status, and you haven't run a request in more than an minute, be sure to run the tool again to get the latest status.