k8s-mcp

一个基于 Python 的只读 模型上下文协议 (MCP) 服务器，用于 Kubernetes 集群，它公开了一个全面的 API 来检索集群信息和诊断问题。

使用 Claude 的示例聊天

安装

前提条件

• Python 3.8+
• 访问 Kubernetes 集群（通过 kubeconfig 或集群内配置）
• 必需的 Python 包（请参阅 pyproject.toml 中的 dependencies）
• uv - https://github.com/astral-sh/uv

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 克隆仓库
git clone git@github.com:vlttnv/k8s-mcp.git
cd k8s-mcp

# 安装依赖
uv venv
source .venv/bin/activate
uv sync

如果使用 Claude，请在文本编辑器中配置您的 Claude for Desktop App 配置，位于 ~/Library/Application Support/Claude/claude_desktop_config.json。 如果该文件不存在，请确保创建它。

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "k8s-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/k8s-mcp",
                "run",
                "server.py"
            ]
        }
    }
}

您可能需要在 command 字段中放入 uv 可执行文件的完整路径。 您可以通过在 MacOS/Linux 上运行 which uv 或在 Windows 上运行 where uv 来获取此路径。

配置

该应用程序自动尝试两种方法来连接到您的 Kubernetes 集群：

1. Kubeconfig 文件：使用您的本地 kubeconfig 文件（通常位于 ~/.kube/config）
2. 集群内配置：如果在 Kubernetes pod 中运行，则使用服务帐户令牌

如果您的 kubeconfig 设置正确，或者您在具有适当 RBAC 权限的集群中运行，则无需其他配置。

用法

示例

以下是一些有用的示例提示，您可以向 Claude 询问有关您的 Kubernetes 集群及其资源的信息：

常规集群状态

• "我的集群的整体健康状况如何？"
• "显示我集群中的所有命名空间"
• "我的集群中有哪些节点可用，它们的状态是什么？"
• "我的节点上的资源利用率如何？"

Pod 和 Deployment

• "列出生产命名空间中的所有 pod"
• "是否有任何 pod 处于 CrashLoopBackOff 状态？"
• "显示我具有高重启次数的 pod"
• "列出所有命名空间中的所有 deployment"
• "哪些 deployment 无法取得进展？"

调试问题

• "为什么我的 pod 在 staging 命名空间中失败？"
• "获取生产命名空间中服务的 YAML 配置"
• "显示我默认命名空间中最近的事件"
• "是否有任何 pod 卡在 Pending 状态？"
• "是什么导致我的集群中出现 ImagePullBackOff 错误？"

资源管理

• "显示我集群中节点的资源消耗"
• "是否有任何我应该清理的孤立资源？"
• "列出生产命名空间中的所有服务"
• "比较 staging 和 production 之间的资源请求"

特定资源检查

• "显示我 kube-system 中 coredns deployment 的配置"
• "获取 staging 中 reverse-proxy 服务的详细信息"
• "pod xyz 中运行了哪些容器？"
• "显示我失败 pod 的日志"

API 参考

命名空间

• get_namespaces()：列出集群中所有可用的命名空间

Pod

• list_pods(namespace=None)：列出所有 pod，可以选择按命名空间过滤
• failed_pods()：列出所有处于 Failed 或 Error 状态的 pod
• pending_pods()：列出所有处于 Pending 状态的 pod，并提供原因
• high_restart_pods(restart_threshold=5)：查找重启次数超过阈值的 pod

节点

• list_nodes()：列出所有节点及其状态
• node_capacity()：显示所有节点上的可用容量

Deployment & 服务

• list_deployments(namespace=None)：列出所有 deployment
• list_services(namespace=None)：列出所有服务
• list_events(namespace=None)：列出所有事件

资源管理

• orphaned_resources()：列出没有所有者引用的资源
• get_resource_yaml(namespace, resource_type, resource_name)：获取特定资源的 YAML 配置

许可证

MIT 许可证

贡献

欢迎贡献！ 请随时提交 Pull Request。