Kube Lint MCP

kube-lint-mcp

mcp名称：io.github.sophotechlabbs/kube-lint-mcp

MCP服务器，在您提交之前验证Kubernetes清单、Helm图表和ArgoCD应用程序，防止部署和GitOps协调失败。

运作原理

You: "Validate the flux manifests in ./k8s/infrastructure/"

Claude: calls list_kube_contexts → presents list → you confirm "staging"
        calls select_kube_context → flux_dryrun

  FluxCD Dry-Run Validation
  Context: staging
  ================================================
  File: infrastructure/redis.yaml
    Client dry-run: PASS
    Server dry-run: PASS

  File: infrastructure/postgres.yaml
    Client dry-run: PASS
    Server dry-run: FAIL
      Error: namespace "db" not found
  ================================================
  Summary: 1 passed, 1 failed

  DO NOT COMMIT - Fix errors first!

没有标志，没有CLI参数——AI代理会自动选择正确的工具。

先决条件

• Python 3.12+
• kubectl 的 配置了群集访问权限
• 舵 （用于Helm图表验证）
• 通量 （适用于Flux操作）
• argocd （用于ArgoCD操作——用途 --core 模式，无需服务器身份验证）

安装

pip（需要单独安装CLI工具）

pip install kube-lint-mcp

Docker（包括电池）

Docker镜像附带kubectl、helm、flux、kubeconform和argocd，无需本地安装。

docker pull ghcr.io/sophotechlabs/kube-lint-mcp:latest

备注：如果你的kubeconfig使用外部身份验证插件（例如。 gke-gcloud-auth-plugin, aws-iam-authenticator)，这些二进制文件不包含在映像中。对这些集群使用pip install方法，或者直接在kubeconfig中嵌入令牌。

配置

克劳德代码（pip）

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "kube-lint": {
      "command": "python",
      "args": ["-m", "kube_lint_mcp"]
    }
  }
}

克劳德代码（Docker）

{
  "mcpServers": {
    "kube-lint": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${HOME}:${HOME}:ro",
        "-e", "KUBECONFIG=${HOME}/.kube/config",
        "ghcr.io/sophotechlabs/kube-lint-mcp:latest"
      ]
    }
  }
}

这 $HOME:$HOME:ro mount保留了MCP客户端发送到服务器的绝对路径。只读标志可确保容器无法修改您的文件。

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%/Claude/claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "kube-lint": {
      "command": "python",
      "args": ["-m", "kube_lint_mcp"]
    }
  }
}

工具

select_kube_context

选择集群上下文。仅存储在内存中-- 永远不要改变你的kubeconfig。必须在任何验证工具之前调用。

list_kube_contexts

使用当前（kubeconfig默认）和选定（内存中）上下文的标记显示可用的kubectl上下文。没有参数。

flux_dryrun

使用客户端和服务器端kubectl dry-run验证FluxCD YAML文件。捕获架构错误、缺少CRD、命名空间问题和不推荐使用的API版本。

You: "Validate the flux manifests in k8s/infrastructure/"

kustomize_dryrun

构建Kustomize覆盖层，并使用kubectl dry-run验证渲染输出。运行整个管道： kustomize build → 客户试运行→ 服务器模拟运行。

You: "Dry-run the staging kustomize overlay in k8s/overlays/staging/"

赫尔姆德赖伦

端到端Helm图表验证： helm lint → helm template → 客户试运行→ 服务器模拟运行。捕获图表错误、模板呈现问题和无效的呈现清单。

You: "Validate the nginx helm chart in charts/nginx/ with staging values"

flux_check

通过运行以下命令验证Flux安装运行状况 flux check报告控制器状态和版本兼容性。没有参数。

通量状态

显示所有命名空间中所有资源的Flux协调状态(flux get all -A).可用于检查资源是否已同步或卡住。没有参数。

argocd_app_list

列出所有具有同步和健康状态的ArgoCD应用程序。用途 --core mode——通过kubeconfig连接，无需ArgoCD服务器身份验证。

You: "List all ArgoCD applications"

argocd_app_get

获取单个ArgoCD应用程序的详细状态，包括同步/运行状况、条件和每个资源的细分。

You: "Show me the status of the my-app ArgoCD application"

argocd_app_diff

显示ArgoCD应用程序的实时状态和所需状态之间的统一差异。指示应用程序是否处于同步状态，或者下次同步时会发生什么变化。

You: "Show me what would change if we sync the my-app ArgoCD application"

yaml-validate

验证Kubernetes清单文件的YAML语法。捕获语法错误、重复键和制表符缩进。 不需要群集连接。

kubeconform_validate

针对Kubernetes JSON模式的离线模式验证。 不需要群集连接。 捕获无效字段、类型不匹配和缺少必填字段。

You: "Validate all manifests in k8s/ against Kubernetes 1.29 with strict mode"

典型工作流程

FluxCD/Helm/Kustomize

1. list_kube_contexts --查看可用集群
2. select_kube_context --目标集群（仅在内存中，从不改变kubeconfig）
3. flux_dryrun, kustomize_dryrun，或 helm_dryrun --提交前验证
4. 仅在所有检查通过时提交

ArgoCD

1. list_kube_contexts / select_kube_context --选择一个集群
2. argocd_app_list --查看所有应用及其同步/运行状况
3. argocd_app_get --深入了解特定应用程序的资源和条件
4. argocd_app_diff --看看下一次同步会有什么变化

对于没有集群的离线验证，请使用 kubeconform_validate 或 yaml_validate 直接——不需要上下文选择。

安全

服务器 永远不要改变你的kubeconfig上下文保存在内存中，并通过以下方式传递 --context 标记每个子流程调用。这是一个针对代理使用的深思熟虑的安全选择——人工智能不会意外切换您的全局kubectl上下文。

所有验证工具 只读 --他们使用 kubectl apply --dry-run 其在不应用的情况下进行模拟。不会创建、修改或删除任何资源。

配置参考

环境变量

在MCP服务器配置中设置这些：

{
  "mcpServers": {
    "kube-lint": {
      "command": "python",
      "args": ["-m", "kube_lint_mcp"],
      "env": {
        "KUBE_LINT_KUBECTL_TIMEOUT": "120"
      }
    }
  }
}

故障排除

“未找到kubectl”或“未找到helm”

pip安装只安装Python包。您需要将kubectl、helm和flux分别安装在您的 PATHDocker镜像包含所有工具——如果你不想管理CLI安装，可以使用它。

Docker：“无法加载kubeconfig”或身份验证错误

确保你的kubeconfig在容器内是可访问的。这 $HOME:$HOME:ro mount以只读方式映射您的主目录。如果你的kubeconfig引用了外部文件 $HOME （例如。 /etc/kubernetes/)，把那些小路也装上去。

如果你的kubeconfig使用 身份验证插件 （GKE、EKS），插件二进制文件不在Docker镜像中。要么：

• 请改用pip安装方法
• 或者为Docker镜像生成一个静态令牌/证书kubeconfig

“未选择上下文”错误

总是打电话 select_kube_context （或者让代理人打电话 list_kube_contexts 首先）在运行任何验证工具之前。服务器不会从kubeconfig读取默认上下文——这是出于安全考虑。

例外情况： kubeconform_validate 离线工作，不需要上下文。

大型图表或慢速集群上的超时

通过环境变量增加相关超时时间。对于在API服务器上使用许多模板的Helm图表：

{
  "env": {
    "KUBE_LINT_KUBECTL_TIMEOUT": "120",
    "KUBE_LINT_HELM_TIMEOUT": "120"
  }
}

服务器模拟运行失败，但客户端模拟运行通过

这是意料之中的。客户端模拟运行在本地验证语法和模式。服务器干式运行将清单发送到API服务器，后者检查附加约束：命名空间存在、CRD可用性、准入webhook、资源配额。在提交之前修复服务器端问题。

“找不到argocd”

安装ArgoCD命令行界面： brew install argocd （macOS）或从下载 发布Docker镜像包括ArgoCD CLI。

ArgoCD--核心模式

所有ArgoCD工具都使用 --core 模式，直接通过kubeconfig连接——不需要ArgoCD服务器身份验证。这要求在群集上安装ArgoCD CRD（应用程序、AppProject）。

kubeconform报告“跳过”的资源

自定义资源定义（CRD）没有上游模式。kubeconform跳过它无法验证的资源。对于FluxCD、证书管理器和其他CRD重型堆栈来说，这是正常的。

发展

pip install -e ".[dev]"
make test    # 100% coverage
make lint    # ruff

贡献

1. 分叉回购
2. 创建要素分支
3. 确保 make test 和 make lint 通过
4. 打开PR

许可证

麻省理工学院

______________________________________________________________________

如果此工具使您免于糟糕的部署，请考虑 赞助.