Kubernetes Tools MCP Server

Kubernetes工具

此包提供了一组Kubernetes函数供代理使用。他们可以通过 直接作为工具发送到代理或放置在MCP服务器（包括在内）后面。一些用例包括：

• 通过GitHub CoPilot或Cursor与您的kubernetes集群聊天。
• 构建 代理 监控集群或执行根本原因分析。
• Vibe代码自定义聊天UI。
• 用于非代理自动化。

方法论

我们的目标是注重质量而非数量——提供 文档齐全、类型强大的工具。我们认为，这对于实现 代理可以有效地利用工具，而不仅仅是简单的演示。

这些构建在kubernetes Python API之上(https://github.com/kubernetes-client/python). 这里提供了三种类型的工具：

1. 有一些工具可以模拟kubectl命令的输出（例如。 get_pod_summaries，这是等效的

向 kubectl get pods).强类型Pydantic模型用于这些工具的返回值。

1. 有一些工具返回强类型的Pydantic模型，试图匹配相关的Kubernetes

客户端类型（请参见https://github.com/kubernetes-client/python/tree/master/kubernetes/docs). 这些模型中可以省略较少使用的字段。这种情况的一个例子是 get_pod_container_statuses.

1. 在某些情况下，我们只是打电话 to_dict() 在API返回的类上（定义于

https://github.com/kubernetes-client/python/tree/master/kubernetes/client/models). 返回类型为 dict[str,Any]，但我们在函数的docstring中记录字段。 get_pod_spec 就是这种工具的一个例子。

目前，优先级是不修改集群状态的功能。 我们想首先关注监控/RCA用例。当我们添加工具来解决问题时 在其他用例中，它们将与只读工具分开，这样您仍然可以构建 “安全”代理人。

安装

经由 pip:

pip install k8stools

经由 uv:

uv add k8stools

当前工具

这些是我们定义的工具：

• get_namespaces -获取命名空间列表，如 kubectl get namespace
• get_node_summaries -获取节点列表，例如 kubectl get nodes -o wide
• get_pod_summaries -获取Pod列表，例如 kubectl get pods -o wide
• get_pod_container_statuses -返回pod中每个容器的状态
• get_pod_events -返回pod的事件
• get_pod_spec -检索给定pod的规格
• get_logs_for_pod_and_container -从pod和容器中检索日志
• get_deployment_summaries -获取部署列表，例如 kubectl get deployments
• get_service_summaries -获取服务列表，例如 kubectl get services

我们还定义了一组有助于调试的相关“print\_”函数：

• print_namespaces
• print_node_summaries
• print_pod_summaries
• print_pod_container_statuses
• print_pod_events
• print_pod_spec
• print_deployment_summaries
• print_service_summaries

使用工具

直接在代理中使用

核心工具在 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]

将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虚拟环境预计将 .venv 在VSCode工作区的根目录下
2. 您已将k8stools软件包安装到工作区中
3. 环境文件 .envrc 包含您需要定义的任何变量。特别是，您可能需要

集 KUBECONFIG 指向你的 kubectl 配置文件。

使用带有流式HTTP传输的MCP

这 *可流式传输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
 ### MCP集成
>
> 运行服务器： `k8s-mcp-server [--transport stdio|streamable-http]`
> 工具通过自动注册 `Tool.from_function()` 在……里面 `mcp_server.py`
>
> 在回答有关用户kubernetes集群的问题时，请使用
> 此服务器提供的工具，配置在 `mcp.json` 像
> `k8stools-stdio`回答这些问题时的其他一些考虑因素
> 问题：
>
> - 如果答案包含多个相似的条目，请格式化为表格
>   如果可能的话。
> - 在提供pod状态时，一定要包括pod的状态。
> - 在提供状态时，使用图标快速显示是好是坏。
> - 如果系统要求您提供当前状态，但您尚未在中运行请求
>   超过一分钟，请确保再次运行该工具以获取最新状态。