kube-lint-mcp

mcp-name: io.github.sophotechlabs/kube-lint-mcp

MCP server that validates Kubernetes manifests, Helm charts, and ArgoCD applications before you commit — preventing deployment and GitOps reconciliation failures.

Works with Claude Code, Claude Desktop, and any MCP-compatible client.

How it works

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!

No flags, no CLI args — the AI agent picks the right tool automatically.

Prerequisites

• Python 3.12+
• kubectl configured with cluster access
• helm (for Helm chart validation)
• flux (for Flux operations)
• argocd (for ArgoCD operations — uses --core mode, no server auth needed)

Installation

pip (requires CLI tools installed separately)

pip install kube-lint-mcp

Docker (batteries included)

The Docker image ships with kubectl, helm, flux, kubeconform, and argocd — no local installs needed.

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

Note: If your kubeconfig uses external auth plugins (e.g. gke-gcloud-auth-plugin, aws-iam-authenticator), those binaries are not included in the image. Use the pip install method for those clusters, or embed tokens directly in your kubeconfig.

Configuration

Claude Code (pip)

Add to your project's .mcp.json:

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

Claude Code (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"
      ]
    }
  }
}

The $HOME:$HOME:ro mount preserves absolute paths that MCP clients send to the server. The read-only flag ensures the container cannot modify your files.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

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

Tools

select_kube_context

Pick a cluster context. Stored in memory only — never mutates your kubeconfig. Must be called before any validation tool.

list_kube_contexts

Show available kubectl contexts with markers for the current (kubeconfig default) and selected (in-memory) context. No parameters.

flux_dryrun

Validate FluxCD YAML files with both client-side and server-side kubectl dry-run. Catches schema errors, missing CRDs, namespace issues, and deprecated API versions.

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

kustomize_dryrun

Build a Kustomize overlay and validate the rendered output with kubectl dry-run. Runs the full pipeline: kustomize build → client dry-run → server dry-run.

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

helm_dryrun

End-to-end Helm chart validation: helm lint → helm template → client dry-run → server dry-run. Catches chart errors, template rendering issues, and invalid rendered manifests.

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

flux_check

Verify Flux installation health by running flux check. Reports controller status and version compatibility. No parameters.

flux_status

Show Flux reconciliation status for all resources across all namespaces (flux get all -A). Useful for checking if resources are synced or stuck. No parameters.

argocd_app_list

List all ArgoCD applications with sync and health status. Uses --core mode — connects via kubeconfig, no ArgoCD server auth needed.

You: "List all ArgoCD applications"

argocd_app_get

Get detailed status of a single ArgoCD application including sync/health status, conditions, and per-resource breakdown.

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

argocd_app_diff

Show unified diff between live and desired state of an ArgoCD application. Indicates whether the app is in sync or what would change on the next sync.

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

yaml_validate

Validate YAML syntax of Kubernetes manifest files. Catches syntax errors, duplicate keys, and tab indentation. Does not require a cluster connection.

kubeconform_validate

Offline schema validation against Kubernetes JSON schemas. Does not require a cluster connection. Catches invalid fields, type mismatches, and missing required fields.

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

Typical workflow

FluxCD / Helm / Kustomize

1. list_kube_contexts — see available clusters
2. select_kube_context — target a cluster (in-memory only, never mutates kubeconfig)
3. flux_dryrun, kustomize_dryrun, or helm_dryrun — validate before committing
4. Only commit when all checks pass

ArgoCD

1. list_kube_contexts / select_kube_context — pick a cluster
2. argocd_app_list — see all apps and their sync/health status
3. argocd_app_get — drill into a specific app's resources and conditions
4. argocd_app_diff — see what would change on the next sync

For offline validation without a cluster, use kubeconform_validate or yaml_validate directly — no context selection needed.

Safety

The server never mutates your kubeconfig. Context is held in memory and passed via --context flag on every subprocess call. This is a deliberate safety choice for agentic use — the AI cannot accidentally switch your global kubectl context.

All validation tools are read-only — they use kubectl apply --dry-run which simulates without applying. No resources are created, modified, or deleted.

Configuration reference

Environment variables

Set these in your MCP server config:

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

Troubleshooting

"kubectl not found" or "helm not found"

The pip install only installs the Python package. You need kubectl, helm, and flux installed separately and on your PATH. The Docker image includes all tools — use it if you don't want to manage CLI installations.

Docker: "unable to load kubeconfig" or auth errors

Make sure your kubeconfig is accessible inside the container. The $HOME:$HOME:ro mount maps your home directory read-only. If your kubeconfig references files outside $HOME (e.g. /etc/kubernetes/), mount those paths too.

If your kubeconfig uses auth plugins (GKE, EKS), the plugin binaries aren't in the Docker image. Either:

• Use the pip install method instead
• Or generate a static token/certificate kubeconfig for the Docker image

"context not selected" errors

Always call select_kube_context (or let the agent call list_kube_contexts first) before running any validation tool. The server does not read a default context from kubeconfig — this is intentional for safety.

Exception: kubeconform_validate works offline and does not need a context.

Timeouts on large charts or slow clusters

Increase the relevant timeout via environment variables. For a Helm chart with many templates against a slow API server:

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

Server dry-run fails but client dry-run passes

This is expected. Client dry-run validates syntax and schema locally. Server dry-run sends the manifest to the API server which checks additional constraints: namespace existence, CRD availability, admission webhooks, resource quotas. Fix the server-side issue before committing.

"argocd not found"

Install the ArgoCD CLI: brew install argocd (macOS) or download from releases. The Docker image includes the ArgoCD CLI.

ArgoCD --core mode

All ArgoCD tools use --core mode, which connects directly via your kubeconfig — no ArgoCD server authentication is needed. This requires that the ArgoCD CRDs (Application, AppProject) are installed on the cluster.

kubeconform reports "skipped" resources

Custom Resource Definitions (CRDs) don't have upstream schemas. kubeconform skips resources it can't validate. This is normal for FluxCD, cert-manager, and other CRD-heavy stacks.

Development

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

Contributing

1. Fork the repo
2. Create a feature branch
3. Make sure make test and make lint pass
4. Open a PR

License

MIT

If this tool saves you from a bad deploy, consider sponsoring.