k8s-mcp-server

一个基于 MCP（Model Context Protocol） 的 Kubernetes 运维助手。它将 K8s 集群的查询能力封装成标准化的 MCP 工具，让 LLM 客户端（如 ZCode、Claude Desktop、Cursor）能够通过自然语言查看和排查 Kubernetes 集群。

功能特性

• 基于 MCP Python SDK，使用 stdio 传输
• 支持多集群切换（本地 k3s / 阿里云 k3s）
• 完善的异常处理，错误信息对 LLM 友好
• 输出经过精简格式化，避免返回冗余的 K8s 原始对象

工具列表

工具	说明
ping	健康检查，返回 pong
list_namespaces	列出所有 namespace 及其状态
list_pods	列出指定 namespace 下的 Pod
describe_pod	查看 Pod 详情（状态、IP、节点、容器、重启次数、资源）
get_pod_logs	获取 Pod 日志（支持 tail_lines 限制行数）
list_nodes	列出集群节点及状态、OS、K8s 版本
list_events	列出所有 namespace 的最近事件（按时间倒序）

环境要求

• Python 3.12+
• uv 包管理器
• 可访问的 Kubernetes 集群及对应的 kubeconfig

安装

git clone git@github.com:AmazingYe-oss/k8s-mcp-server.git
cd k8s-mcp-server
uv sync

配置

默认从以下路径加载 kubeconfig（在 src/k8s_mcp_server/k8s_client.py 中配置）：

• local → ~/.kube/config
• cloud → ~/.kube/config-k3s-cloud

如需修改集群映射，编辑 KUBECONFIGS 字典即可。

运行

uv run k8s-mcp-server

服务器以 stdio 模式启动，等待 MCP 客户端连接。

MCP 客户端配置

ZCode / Claude Desktop（Windows 连接 WSL 中的 Server）

{
  "mcp": {
    "servers": {
      "k8s": {
        "type": "stdio",
        "command": "wsl",
        "args": [
          "bash",
          "-lc",
          "cd /home/<your-user>/k8s-mcp-server && uv run k8s-mcp-server"
        ]
      }
    }
  }
}

原生 Linux/macOS

{
  "mcp": {
    "servers": {
      "k8s": {
        "type": "stdio",
        "command": "uv",
        "args": ["--directory", "/path/to/k8s-mcp-server", "run", "k8s-mcp-server"]
      }
    }
  }
}

项目结构

src/k8s_mcp_server/
├── __init__.py
├── server.py        # MCP Server 入口，注册工具
├── k8s_client.py    # K8s API 客户端封装与异常处理
└── formatters.py    # K8s 对象到精简文本的格式化

开发

# 代码检查
uv run ruff check .

# 运行测试
uv run pytest