k8s-mcp-server

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

功能特性

• 基于 MCP Python SDK，使用 stdio 传输

• 支持多集群切换（本地 k3s / 阿里云 k3s）

• 8 个工具：健康检查、资源查询、Pod 一键诊断

• diagnose_pod 组合工具：一次调用聚合 Pod 状态、事件、日志，并通过规则引擎给出初步诊断建议

• 完善的异常处理，错误信息对 LLM 友好

• 输出经过精简格式化，避免返回冗余的 K8s 原始对象

• 所有工具均为只读操作，不会修改集群状态

• 28 个 pytest 单元测试，ruff 代码检查

• Docker 多阶段构建，GitHub Actions CI/CD 自动推送镜像至阿里云 ACR

Related MCP server: Multi Cluster Kubernetes MCP Server

工具列表

diagnose_pod 规则引擎

diagnose_pod 不依赖 LLM 做确定性判断，而是用 Python 规则引擎检测常见问题：

规则引擎负责确定性模式匹配（零延迟、100% 一致），LLM 在此基础上做上下文关联和深度分析，将多次工具调用压缩为一次。

环境要求

• Python 3.12+

• uv 包管理器

• 可访问的 Kubernetes 集群及对应的 kubeconfig

快速开始

安装

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

配置 kubeconfig

默认从以下路径加载 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"]
      }
    }
  }
}

Docker

构建镜像

docker build -t k8s-mcp-server:latest .

运行（挂载 kubeconfig）

docker run --rm -v ~/.kube:/home/appuser/.kube:ro k8s-mcp-server:latest

项目结构

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

tests/
├── conftest.py          # 共享 mock fixtures（5 种 Pod 场景）
├── test_formatters.py   # formatter 单元测试
└── test_diagnose.py     # 规则引擎与报告组装测试

开发

# 代码检查
uv run ruff check .
uv run ruff format --check .

# 运行测试
uv run pytest

# 代码格式化
uv run ruff format .

CI/CD

GitHub Actions 流水线（.github/workflows/docker-ci-cd.yml）：

1. PR / push 时：运行 ruff 检查和 pytest

2. 合并到 main 后：构建 Docker 镜像并推送至阿里云 ACR

   • 标签：latest、<git-sha>、语义化版本 tag

需要在 GitHub 仓库配置以下 Secrets：

技术栈

• Python 3.12

• MCP Python SDK

• Kubernetes Python Client

• uv（依赖管理）

• pytest + unittest.mock（单元测试）

• ruff（代码检查与格式化）

• Docker + GitHub Actions + 阿里云 ACR