内容
[](https://github.com/your-ko/mcp-k8s-ro/actions/workflows/main.yaml)
[](https://github.com/your-ko/mcp-k8s-ro/actions/workflows/golangci-lint.yaml)
[](https://github.com/your-ko/mcp-k8s-ro/actions/workflows/link-validator.yaml)
# MCP Kubernetes只读服务器
一个只读的MCP服务器，为Claude提供访问Kubernetes集群的能力。使用Go语言构建，通过stdio使用MCP协议进行通信。
## 设计
- **只读** — 仅支持`get`、`describe`、`logs`和`top`等操作。不支持创建、更新或删除操作。如果需要进行修改操作，服务器会打印出等效的`kubectl`命令，供您手动运行。在夜间值班时使用是安全的：Claude永远不会在提示疲劳的情况下意外修改您的集群。
- **安全保护** — 在将机密值发送到模型之前会进行掩码处理，以防止您的机密因配置错误或提示注入而泄露。
- **高效使用Token** — 响应中只包含相关字段（名称、状态、重启次数等），而不是原始的Kubernetes API对象，从而保持上下文使用率低。
- **集群感知** — 每个响应都包含活动上下文和集群名称，以便Claude始终知道它正在与哪个集群通信。
- **上下文锁定** — 服务器在启动时锁定到活动的kubeconfig上下文。在另一个终端切换上下文不会影响正在运行的服务器。
- **无需额外基础设施** — 作为本地二进制文件或Docker容器运行，连接到启动时活动的任意kubeconfig上下文。
## 已屏蔽字段
| 对象/字段 | 原因 |
|--------------------------------------------------------|----------------------------------------------------------|
| Secret.data | 防止机密泄露 |
| Secret.stringData | 防止机密泄露 |
| CertificateSigningRequest.spec.request | 大型base64 PEM块，无诊断价值，节省Token |
| Certificate (cert-manager) .spec.keystores | 证书链PEM块，无诊断价值，节省Token |
| Certificate (cert-manager) status.conditions[].message | 证书链PEM块，无诊断价值，节省Token |
| *.managedFields | 无诊断价值，节省Token |
## 工具
| 工具 | 描述 |
|---------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `k8s_list_resources` | 按名称列出任何资源类型 — pod、deployment、CRD等。接受可选的命名空间过滤器。返回名称、状态、就绪状态、重启次数、节点、IP等，取决于资源类型。 |
| `k8s_describe_resource` | 返回单个资源的完整YAML。机密数据被掩码。 |
| `k8s_list_resource_types` | 通过发现API列出所有可用的资源类型。接受可选的API组过滤器。 |
| `k8s_get_logs` | 获取pod日志。支持容器选择器、尾部行和`--previous`用于崩溃的容器。 |
| `k8s_get_events` | 列出命名空间或整个集群的Kubernetes事件，按最新事件排序。 |
| `k8s_top_pods` | 每个pod的CPU和内存使用情况，包含每个容器的详细信息。需要metrics-server。 |
| `k8s_top_nodes` | 每个节点的CPU和内存使用情况，包含可分配容量的百分比。需要metrics-server。 |
## 配置
| 环境变量 | 默认值 | 描述 |
|----------------------|------------------|-------------------------|
| `KUBECONFIG` | `~/.kube/config` | kubeconfig文件路径 |
## 与Claude一起使用
### 二进制文件
构建二进制文件并将其添加到Claude Desktop或`claude` CLI配置中：
```bash
make build
# 二进制文件写入 bin/mcp-k8s-ro
```
```json
{
"mcpServers": {
"k8s": {
"type" : "stdio",
"command": "/path/to/bin/mcp-k8s-ro",
"env": {
"KUBECONFIG": "/path/to/.kube/config"
}
}
}
}
```
或通过CLI：
```bash
claude mcp add --transport stdio --scope user mcp-k8s-ro [二进制文件路径]
```
### Docker
从GitHub容器注册表中拉取镜像（建议固定特定版本）：
```bash
docker pull ghcr.io/your-ko/mcp-k8s-ro:latest
```
将其添加到Claude Desktop或`claude` CLI配置中。kubeconfig目录以只读方式挂载到容器中：
```json
{
"mcpServers": {
"k8s": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-v", "/path/to/.kube:/home/nonroot/.kube:ro",
"ghcr.io/your-ko/mcp-k8s-ro:latest"
]
}
}
}
```
如果您的kubeconfig位于非标准位置，请通过`KUBECONFIG`传递：
```json
{
"mcpServers": {
"k8s": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "KUBECONFIG=/config/my-kubeconfig",
"-v", "/path/to/my-kubeconfig:/config/my-kubeconfig:ro",
"ghcr.io/your-ko/mcp-k8s-ro:latest"
]
}
}
}
```
## 单集群设计
服务器故意在单个kubeconfig上下文中运行，不提供在运行时切换集群的工具。原因是：
- **提示注入隔离** — 恶意值不能在单个集群的资源中（例如pod注释）指示Claude切换到不同的集群，包括生产环境。
- **明确的审计边界** — 每个工具响应都包含上下文和集群名称，因此永远不会混淆查询了哪个集群。
**要将服务器指向不同的集群**，停止服务器，切换上下文，然后重启：
```bash
kubectl config use-context my-other-cluster
# 然后重启MCP服务器/重新加载Claude Desktop
```
**要同时使用多个集群**，在MCP配置中为每个集群注册一个单独的服务器实例：
```json
{
"mcpServers": {
"k8s-staging": {
"type": "stdio",
"command": "/path/to/bin/mcp-k8s-ro",
"env": { "KUBECONFIG": "/path/to/.kube/config" }
},
"k8s-prod": {
"type": "stdio",
"command": "/path/to/bin/mcp-k8s-ro",
"env": { "KUBECONFIG": "/path/to/.kube/config-prod" }
}
}
}
```
Claude将按名称寻址每个服务器，每个实例仅看到其自己的集群。
## MCP注册表
该服务器已发布在 [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/?q=mcp-k8s-ro) 上。
