mcp-kubernetes-server

mcp-kubernetes-server

mcp-kubernetes-server 是一个实现模型上下文协议（MCP）的服务，可让 AI 助手（例如 Claude、Cursor 和 GitHub Copilot）与 Kubernetes 集群交互。它充当桥梁，将这些助手发出的自然语言请求转换为 Kubernetes 操作，并返回结果。

它支持 AI 助手：

• 查询 Kubernetes 资源
• 执行 kubectl 命令
• 通过自然语言交互管理 Kubernetes 集群
• 诊断并解读 Kubernetes 资源的状态

工作原理

mcp-kubernetes-server 充当支持模型上下文协议的 AI 助手与 Kubernetes 集群之间的中间层。它接收这些助手发出的自然语言请求，将其转换为 kubectl 命令或直接的 Kubernetes API 调用，并在目标集群上执行。随后，服务会处理结果并返回结构化响应，让用户能够通过 AI 助手与 Kubernetes 环境无缝交互。

安装方法

前提条件

安装 mcp-kubernetes-server 之前，请确保具备以下条件：

• 一个可正常运行的 Kubernetes 集群。
• 一个已正确配置、可访问 Kubernetes 集群的 kubeconfig 文件（服务需要使用此文件进行交互）。
• 已安装并添加到系统 PATH 中的 kubectl 命令行工具（服务会使用它执行许多 Kubernetes 命令）。
• 已安装并添加到系统 PATH 中的 helm 命令行工具（服务会使用它执行 Helm chart 操作）。
• Python >= 3.11（如果计划使用 uvx 直接安装并运行服务，而不使用 Docker）。

Docker

获取 Kubernetes 集群的 kubeconfig 文件，并在 mcpServers 中进行配置（将 src 路径替换为你的 kubeconfig 路径）：

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/home/username/.kube/config,dst=/home/mcp/.kube/config",
        "ghcr.io/feiskyer/mcp-kubernetes-server"
      ]
    }
  }
}

UVX

要使用 uvx（uv 这个 Python 包管理器附带的工具）运行服务，请先确保已安装 uv：

# For Linux and MacOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# For Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

# For MacOS
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/darwin/arm64/kubectl"

curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

在 Claude Desktop、Cursor、ChatGPT Copilot、Github Copilot 和其他受支持的 AI 客户端中配置 MCP 服务，例如：

{
  "mcpServers": {
    "kubernetes": {
      "command": "uvx",
      "args": [
        "mcp-kubernetes-server"
      ],
      "env": {
        "KUBECONFIG": "<your-kubeconfig-path>"
      }
    }
  }
}

MCP 服务选项

usage: main.py [-h] [--disable-kubectl] [--disable-helm] [--disable-write]
               [--disable-delete] [--transport {stdio,sse,streamable-http}]
               [--host HOST] [--port PORT]

MCP Kubernetes Server

options:
  -h, --help            show this help message and exit
  --disable-kubectl     Disable kubectl command execution
  --disable-helm        Disable helm command execution
  --disable-write       Disable write operations
  --disable-delete      Disable delete operations
  --transport {stdio,sse,streamable-http}
                        Transport mechanism to use (stdio or sse or streamable-http)
  --host HOST           Host to use for sse or streamable-http server
  --port PORT           Port to use for sse or streamable-http server

在 AI 客户端中安装并配置 mcp-kubernetes-server（使用“如何安装”部分提供的 Docker 或 UVX JSON 代码片段）后，你就可以通过自然语言与 Kubernetes 集群交互。例如，你可以询问：

What is the status of my Kubernetes cluster?

What is wrong with my nginx pod?

**验证服务：**如果你使用 stdio 传输方式运行服务（uvx 直接执行时常用），AI 客户端通常会启动并管理服务进程。对于 sse 或 streamable-http 传输方式，服务会独立运行。你需要手动启动它（例如，uvx mcp-kubernetes-server --transport sse），并且应该能在终端中看到服务正在运行的输出（例如，INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)）。如果 AI 客户端连接失败，也可以在服务终端中检查是否有错误消息。

可用工具

mcp-kubernetes-server 提供了一套全面的工具，用于与 Kubernetes 集群交互，并按操作类型分类：

开发

如何在本地运行项目：

uv run -m src.mcp_kubernetes_server.main

如何检查 MCP 服务的请求和响应：

npx @modelcontextprotocol/inspector uv run -m src.mcp_kubernetes_server.main

故障排除

以下是使用 mcp-kubernetes-server 时的一些常见问题及其解决方案：

问题： mcp-kubernetes-server 无法连接到 Kubernetes 集群或报告身份验证错误。 解决方案：

• 确保正确配置了 kubeconfig 文件，并且指向预期的集群。
• 确认在 mcpServers 配置中正确指定了 kubeconfig 文件的路径（对于 Docker，请确保挂载路径正确；对于 uvx，请确保正确设置了 KUBECONFIG 环境变量）。
• 检查 kubeconfig 中的凭据是否具备在集群上执行操作所需的权限。可以直接使用 kubectl 测试（例如，kubectl get pods）。

问题： kubectl 或 helm 命令返回类似 "command not found" 的错误，或被禁用。 解决方案：

• 如果通过 uvx 运行，请确保系统已安装 kubectl 和/或 helm，并且它们位于 PATH 中。安装说明请参阅“先决条件”部分。
• 如果看到类似 "Write operations are not allowed" 或 "Delete operations are not allowed" 的消息，则服务可能是通过 --disable-kubectl、--disable-helm、--disable-write 或 --disable-delete 等标志启动的。请检查服务的启动命令以及 README 中的“MCP 服务选项”部分，了解这些标志的详情。

问题： 如何查看 AI 客户端与 mcp-kubernetes-server 之间的原始请求和响应？ 解决方案：

• 可以使用“开发”部分提到的 @modelcontextprotocol/inspector 工具：npx @modelcontextprotocol/inspector uv run -m src.mcp_kubernetes_server.main。这将显示正在交换的 MCP 消息。

问题： 服务已启动，但 AI 客户端无法连接。 解决方案：

• 如果使用 stdio 传输（uvx 直接执行时的默认方式），请确保 AI 客户端已正确配置为启动 mcp-kubernetes-server 命令。
• 如果使用 sse 或 streamable-http 传输，请确保在 mcp-kubernetes-server 中配置的主机和端口（例如，--host 0.0.0.0 --port 8000）可从 AI 客户端所在位置访问。检查防火墙规则或网络配置是否存在问题。此外，请确认 AI 客户端配置了正确的服务 URL。

贡献

此项目在 GitHub 上开源，地址为 feiskyer/mcp-kubernetes-server，并采用 Apache License 许可。

如果您想为此项目做出贡献，请遵循以下指南：

1. Fork 此仓库并将其克隆到本地计算机。
2. 为您的更改创建一个新分支。
3. 进行更改，并使用描述性提交消息提交。
4. 将更改推送到您 Fork 的仓库。
5. 向主仓库提交 Pull Request。

许可证

此项目采用 Apache License 2.0 许可。更多详情请参阅 LICENSE 文件。