内容
# k8s-mcp-go
**适用于 AI 代理的安全、默认只读的 Kubernetes 访问方式**
一个 Kubernetes MCP 服务器，允许 AI 助手安全地检查您的集群，而无需给予它们不受限制的 `kubectl` 权限。
## 有什么不同
- **默认只读**：适用于无需 AI 修改集群的诊断场景。
- **明确的权限模式**：在 AI 助手启动前，选择 `readonly`、`readwrite` 或 `dangerous`。
- **无需 Docker**：通过 MCPB 包或单个原生二进制文件进行安装。
- **Kubernetes 原生可见性**：检查 Pod、部署、服务、日志、事件、节点和实时 CPU/内存使用情况。
- **注册表就绪分发**：作为 `io.github.kaneg/k8s-mcp-go` 发布，供 MCP 注册表消费者和打包客户端使用。
## 分发
- [MCP 注册表](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.kaneg/k8s-mcp-go): 发布为 `io.github.kaneg/k8s-mcp-go`。
- [PulseMCP](https://www.pulsemcp.com/servers/kaneg-k8s-mcp-go): 从 MCP 生态系统索引，使用官方 `server.json`。
- [Claude 代码市场](https://claudemarketplaces.com/mcp/kaneg-k8s-mcp-go): 列出带有 MCPB 安装元数据。
## 为什么
大多数 AI 代理可以使用 Kubernetes 工具。
真正的问题是**如何阻止它们更改错误的内容**。
给予 AI 原始 `kubectl` 访问权限存在风险。即使是能力出众的模型也可能：
- 删除错误资源
- 重启错误工作负载
- 应用危险更改
- 将调试会话转变为生产事件
`k8s-mcp-go` 为 AI 代理提供了一个**受限的 Kubernetes 接口**，而不是无限制的 shell 访问。
它的设计基于一个现实问题：
> 如何在不让 AI 破坏我的集群的情况下，让它帮助处理 Kubernetes？
## 权限模式
您预先选择边界：
| 您想要的 | 模式 |
|---------------|------|
| “让 AI 检查和诊断，但不做任何更改” | `readonly` |
| “允许安全的操作操作，如扩展和重启” | `readwrite` |
| “给予它完全的集群权限” | `dangerous` |
### `readonly`（默认）
用于诊断、检查和安全探索。
AI 可以执行以下操作：
- 列出 Pod、部署、服务、节点和命名空间
- 读取日志和事件
- 检查集群状态
- 检查资源使用情况
它**不能**修改工作负载或删除资源。
### `readwrite`
用于受控的操作工作流。
AI 可以执行以下操作：
- 扩展部署
- 重启部署
- 重启有状态集
- 更新镜像
- 修补部署
- 创建命名空间
它仍然无法执行最具破坏性的操作。
### `dangerous`
完全访问权限。
仅在您明确希望 AI 能够执行以下操作时使用：
- 删除资源
- 删除命名空间
- 应用任意 YAML
如果您不确定，请使用 `readonly`。
## 快速入门
### 选项 1：MCPB 安装（推荐）
从 [Releases](https://github.com/kaneg/k8s-mcp-go/releases/latest) 下载适用于您平台的 `.mcpb` 包。MCPB 兼容的客户端（Claude Desktop、Cursor 等）可以直接安装 — 无需 Docker，无需 Go，无需手动设置。
| 操作系统 | 架构 | 文件 |
|----|------|------|
| Linux | x86_64 | `k8s-mcp-go_*_linux_amd64.mcpb` |
| Linux | ARM64 | `k8s-mcp-go_*_linux_arm64.mcpb` |
| macOS | Intel | `k8s-mcp-go_*_darwin_amd64.mcpb` |
| macOS | Apple Silicon | `k8s-mcp-go_*_darwin_arm64.mcpb` |
| Windows | x86_64 | `k8s-mcp-go_*_windows_amd64.mcpb` |
| Windows | ARM64 | `k8s-mcp-go_*_windows_arm64.mcpb` |
### 选项 2：手动二进制安装
从 [Releases](https://github.com/kaneg/k8s-mcp-go/releases/latest) 获取二进制存档并解压：
```bash
# 示例：Linux x86_64
tar xzf k8s-mcp-go_*_linux_amd64.tar.gz
chmod +x k8s-mcp-go
sudo mv k8s-mcp-go /usr/local/bin/
```
然后将其添加到您的 MCP 客户端。
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"k8s": {
"command": "k8s-mcp-go",
"args": ["-mode=readonly"]
}
}
}
```
**Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"k8s": {
"command": "k8s-mcp-go",
"args": ["-mode=readonly"]
}
}
}
```
重启您的客户端并开始询问有关集群的问题。
## 示例提示
安装完成后，询问您的 AI 助手以下问题：
- “显示所有命名空间中的不健康 Pod。”
- “哪些 Pod 的内存使用量最大？”
- “总结最近的警告事件。”
- “检查此部署并解释为什么它未就绪。”
- “检查此部署的滚动更新状态。”
在 `readonly` 模式下，助手可以调查但不能更改集群。
## 为什么不直接使用 kubectl？
因为问题不在于 AI 是否能与 Kubernetes 通信，而在于它能否**安全地**通信。
`kubectl` 很强大，但它不为 AI 行为提供产品级权限模式。
使用 `k8s-mcp-go`，您可以决定助手是否可以：
- 仅检查
- 执行有限的操作操作
- 或获得完全控制
**权限边界就是产品。**
## 可用工具（共 35 个）
工具按权限级别分组。
名称以操作动词开头，如 `get`、`list` 或 `delete`；`top_nodes` 和 `top_pods` 保留 Kubernetes 已建立的 `kubectl top` 术语。
### 只读（24 个）
| 工具 | 描述 |
|------|-------------|
| `get_server_info` | 显示服务器版本、模式、Kubernetes 配置源和运行时详细信息 |
| `resolve_workload` | 将应用/工作负载名称解析为匹配的资源和建议的下一个工具 |
| `list_pods` | 列出 Pod；支持 `all_namespaces=true` |
| `get_pod` | 获取 Pod 详细信息 |
| `get_pod_logs` | 获取 Pod 日志 |
| `list_deployments` | 列出部署；支持 `all_namespaces=true` |
| `get_deployment` | 获取部署详细信息 |
| `list_statefulsets` | 列出 StatefulSets；支持 `all_namespaces=true` |
| `get_statefulset` | 获取 StatefulSet 详细信息 |
| `list_services` | 列出服务；支持 `all_namespaces=true` |
| `get_service` | 获取服务详细信息 |
| `list_configmaps` | 列出 ConfigMaps；支持 `all_namespaces=true` |
| `get_configmap` | 获取 ConfigMap 数据 |
| `list_secrets` | 列出 Secret（仅限密钥）；支持 `all_namespaces=true` |
| `get_secret` | 获取 Secret 元数据和密钥 |
| `list_pvc` | 列出 PersistentVolumeClaims；支持 `all_namespaces=true` |
| `list_ingress` | 列出 Ingress 资源；支持 `all_namespaces=true` |
| `list_jobs` | 列出 Job；支持 `all_namespaces=true` |
| `top_nodes` | 当前节点 CPU 和内存使用情况 |
| `top_pods` | 当前 Pod CPU 和内存使用情况 |
| `list_nodes` | 列出集群节点 |
| `list_namespaces` | 列出命名空间 |
| `get_cluster_overview` | 集群健康状况总结 |
| `list_events` | 列出事件 |
### 读写（7 个）
| 工具 | 描述 |
|------|-------------|
| `scale_deployment` | 扩展部署副本 |
| `restart_deployment` | 滚动重启部署 |
| `restart_statefulset` | 滚动重启有状态集 |
| `set_image` | 更新容器镜像 |
| `get_rollout_status` | 检查滚动更新进度 |
| `create_namespace` | 创建新命名空间 |
| `patch_deployment` | 应用战略合并补丁 |
### 危险（7 个）
| 工具 | 描述 |
|------|-------------|
| `delete_pod` | 删除 Pod |
| `delete_deployment` | 删除部署 |
| `delete_statefulset` | 删除 StatefulSet 及其 Pod |
| `delete_daemonset` | 删除 DaemonSet 及其 Pod |
| `delete_resource` | 删除没有专用删除工具的资源 |
| `delete_namespace` | 删除命名空间和所有资源 |
| `apply_yaml` | 应用任意 YAML 清单 |
在存在专用删除工具的情况下，优先使用上述工具。当没有专用工具时，使用 `delete_resource` 作为备用。 它通过 Kubernetes 发现解决了命名空间和集群范围资源的解析。
```json
{"api_version":"v1","kind":"ServiceAccount","namespace":"apps","name":"builder"}
{"api_version":"rbac.authorization.k8s.io/v1","kind":"ClusterRole","name":"auditor"}
```
## Kubernetes 配置
配置按以下顺序选择：
1. 如果设置了 `KUBECONFIG`，则使用指定的文件。
2. Pod 的集群内 ServiceAccount 配置。
3. 在集群外运行时，使用 `~/.kube/config`。
显式的 `KUBECONFIG` 具有权威性。如果无法加载它，服务器将返回错误，而不是静默切换到 Pod 的 ServiceAccount。
集群内配置使用 Kubernetes 挂载的令牌文件，以便投影的 ServiceAccount 令牌轮换继续工作，而无需将令牌复制到 kubeconfig 中。
## 环境变量
| 变量 | 描述 |
|----------|-------------|
| `KUBECONFIG` | 显式的 kubeconfig 路径。未设置时，使用集群内配置或回退到 `~/.kube/config`。 |
## 从源代码构建
```bash
git clone https://github.com/kaneg/k8s-mcp-go.git
cd k8s-mcp-go
go build -o k8s-mcp-go .
```
## 许可证
MIT
