k8s-mcp 将 Kubernetes 运维能力以 MCP 工具暴露给 Claude、Cursor、Cline、Cherry Studio 等 Agent。当前提供 91 个工具，覆盖资源检索、日志与事件、工作负载交付、RBAC/NetworkPolicy 分析、Prometheus、告警通知、集群诊断与 NVIDIA GPU 运维。
[!IMPORTANT] 默认允许读写与删除。 需要审计、演练或诊断时，显式设置
K8S_MCP_READ_ONLY=true进入只读模式。生产写入仍建议配置K8S_MCP_NAMESPACE_ALLOWLIST与最小 RBAC。
为什么选择它
- 安全可控：可随时切换只读模式、namespace 写入边界、每工具限流、调用超时、有界 worker pool、Kubernetes 错误脱敏。
- Agent 友好：工具说明提供参数约束与下一步建议；诊断、解释和分析工具减少“先 list 再猜”的多轮调用。
- 可运营：
doctor命令、可复现的组件 manifest、CI 中的工具数/文档/版本一致性检查。 - 可渐进授权：从只读
view身份开始；仅为需要写入的 namespace 配置窄权限 Role。
5 分钟快速开始
1. 安装并自检
pip install k8s-mcp-bilbilmyc
k8s-mcp --help
k8s-mcp doctor
doctor 不会连接集群，也不会输出 token；它显示生效的默认值、认证来源、传输边界和配置警告。默认输出中 read_only 为 false。
2. 准备 Kubernetes 凭据
export KUBECONFIG="$HOME/.kube/config" # 已使用默认路径时可省略
详细认证路径（kubeconfig、API Server token、in-cluster）见快速开始。
3. 配置 MCP 客户端
{
"mcpServers": {
"k8s": {
"command": "k8s-mcp",
"env": {
"KUBECONFIG": "/absolute/path/to/kubeconfig"
}
}
}
}
k8s-mcp 默认以 stdio 启动；serve 仅保留为显式别名。若客户端能访问默认 ~/.kube/config，上面的 env 也可以省略。客户端配置、Windows 路径和排障请看快速开始。
4. 必要时切换为只读模式
export K8S_MCP_READ_ONLY=true
k8s-mcp doctor
常规写入场景建议仍设置 K8S_MCP_NAMESPACE_ALLOWLIST=staging,preview，并避免使用“无限 namespace + 集群管理员 kubeconfig”。请采用部署与 RBAC 模板。
工具能力一览
| 场景 | 代表工具 |
|---|---|
| 观察与排障 | cluster_health_snapshot、get_pod_logs、list_events、diagnose_pod、explain_pod |
| 工作负载交付 | create_deployment、scale_workload、set_image、rollout_status、wait_for_resource |
| 通用资源操作 | list_resources、get_resource、apply_yaml、diff_resource、delete_resource |
| 安全与网络 | whoami、analyze_rbac、analyze_networkpolicy、audit_secrets |
| 可观测性 | top_pods、top_nodes、prometheus_query、find_prometheus_service |
| NVIDIA GPU / AI 运维 | gpu_cluster_overview、gpu_diagnose、gpu_node_inspect、gpu_workload_inspect、gpu_pending_workloads、gpu_metrics_catalog、gpu_utilization_overview、gpu_workload_utilization、gpu_utilization_history |
| 通知与基础能力 | notify、bootstrap_metrics_server、bootstrap_local_path_provisioner |
完整签名和按功能分类的目录见工具参考。
安全设计
flowchart LR
A["LLM Agent"] --> B["MCP 边界"]
B --> C["限流 / 超时 / 有界并发 / 错误脱敏"]
C --> D["read_only 守门"]
D --> E["namespace allowlist"]
E --> F["Kubernetes API"]
- 只读按需开启：设置
K8S_MCP_READ_ONLY=true后，所有写、patch、apply、delete 类操作都会被read_only守门拒绝。 - 超时不等于中止线程：同步 Kubernetes SDK 请求无法安全强杀；超时后 worker slot 仍占用，直到请求自然结束，避免失控 Agent 堆积后台任务。
- Webhook 防护：默认仅 HTTPS，拒绝字面量私网/回环地址，且禁用自动重定向；企业内网 webhook 需要显式 opt-in。
- 引导组件可复现：默认 manifest 固定到版本，而不是移动的
master或latestURL。
完整威胁模型、环境变量和升级指引见安全模型。
文档导航
| 目标 | 中文 | English |
|---|---|---|
| 安装、认证、客户端配置 | 快速开始 | Quick start |
| 权限、安全、运行策略 | 安全模型 | Security |
| Kubernetes RBAC 部署 | 部署指南 | Deployment |
| NVIDIA GPU / AI 工作负载 | GPU 运维 | GPU operations |
| 全部环境变量 | 环境变量 | Environment |
| 维护者文档索引 | 文档首页 | Documentation |
| 完整工具目录 | 工具参考 | Tool catalog |
开发与发布
uv sync --all-extras --dev
uv run ruff check .
uv run pytest -q
uv run python scripts/pre_release_check.py
每次 CI 会校验测试、lint、工具数、核心中英文文档中的工具数与版本一致性。贡献流程见CONTRIBUTING.md，发版流程见docs/publishing.md。
许可证
以 MIT License 发布。
1 maintainer
Metadata
1 maintainer
Release files for k8s-mcp-bilbilmyc 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| k8s_mcp_bilbilmyc-2.0.0.tar.gz | 489.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| k8s_mcp_bilbilmyc-2.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 689.1 kB
Release files / k8s_mcp_bilbilmyc-2.0.0.tar.gz
| Download URL | k8s_mcp_bilbilmyc-2.0.0.tar.gz |
|---|---|
| Size | 489.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
69110a98449505d01083722682e6dad206fe0398b57944b0cb184cd1696e578f
|
|
BLAKE2b-256 checksum How to use checksums |
7ae7b7e1cd6ba473017077783dc03ddfa2a09f438bcec849dabec414a4849b5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.
Transparency logRelease files / k8s_mcp_bilbilmyc-2.0.0-py3-none-any.whl
| Download URL | k8s_mcp_bilbilmyc-2.0.0-py3-none-any.whl |
|---|---|
| Size | 199.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
805650671d77f7c5cd1096754c722e691f177b259a54fc85d01a1fbeab3ed9ff
|
|
BLAKE2b-256 checksum How to use checksums |
2f25b5ba53c8acaf12a43ece29bc436963e732bccb360a5bb7d8e41e43a07b50
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 31, 2026.
Transparency log
