kube-sre-mcp

Kube SRE MCP

Why | What it can do | Example | Safety | Getting Started | MCP Client Setup | Documentation | Contributing | Security | License

Give your AI assistant an SRE that understands your Kubernetes cluster.

Kube SRE MCP is a Kubernetes troubleshooting and SRE diagnostics MCP server, built in Go with client-go. Its focus is a deterministic diagnostic engine: it collects, normalizes, correlates, and ranks Kubernetes evidence such as status, conditions, Events, logs, dependencies, scheduling signals, storage signals, and optional metrics. The result is a set of ranked diagnostic hypotheses with supporting evidence, confidence, impact, visibility, and recommendations.

There is no embedded LLM. The MCP host selects tools and may interpret or narrate the structured output. Evidence collection, normalization, correlation, and hypothesis ranking run deterministically inside kube-sre-mcp.

Observe → Diagnose → Explain → Safely Act

v0.1.0 scope

• Local execution
• stdio transport
• kubeconfig authentication
• Read-only by default
• No HTTP transport
• No in-cluster ServiceAccount authentication
• No official container image
• Kubernetes RBAC remains the authorization boundary

Diagnostic results are evidence-based hypotheses, not guaranteed causal root-cause analysis.

Why Kube SRE MCP

General-purpose Kubernetes MCP servers provide broad Kubernetes access and operational capabilities.

Kube SRE MCP intentionally focuses on a specialized, deterministic SRE diagnostic layer.

Rather than maximizing the number of Kubernetes operations exposed to an AI agent, Kube SRE MCP concentrates on turning Kubernetes signals into structured diagnostic evidence.

The goal is not to replace kubectl or provide generic Kubernetes CRUD.

The goal is not to replace kubectl or provide generic Kubernetes CRUD.

It is designed to help answer:

• What is unhealthy?
• Why does it appear unhealthy?
• What evidence supports that diagnosis?
• What is impacted?
• How confident is the diagnosis?
• What should be investigated or done next?

Diagnostics-first, not generic CRUD.

                    Kubernetes API
                          │
            ┌─────────────┼─────────────┐
            │             │             │
          Status        Events         Logs
            │             │             │
            └─────────────┼─────────────┘
                          │
                   Dependencies
                   Scheduling
                     Storage
                     Metrics
                          │
                          ▼
                 Normalize Signals
                          │
                          ▼
                 Correlate Evidence
                          │
                          ▼
               Rank Root-Cause
                  Hypotheses
                          │
                          ▼
            Confidence + Impact
                 + Visibility
                          │
                          ▼
                  Recommendations
                          │
                          ▼
              Optional Guarded Actions

What it can do

• Diagnose Pods, Deployments, Services, Nodes and other Kubernetes resources
• Correlate status, Events, logs, dependencies and optional metrics
• Produce deterministic, ranked diagnostic hypotheses with supporting evidence
• Report partial visibility and RBAC gaps instead of treating missing evidence as healthy
• Expose impact and recommendations
• Detect common Kubernetes failures such as CrashLoopBackOff, OOMKilled, image pull, scheduling, storage and backend issues
• Inspect cluster health and unhealthy workloads
• Read Events and logs with redaction
• Diagnose generic Kubernetes resources and CRDs through discovery and status.conditions
• Support guarded optional actions only when explicitly enabled

See CATALOG.md for the complete MCP tool list, schemas, arguments and RBAC requirements.

Example

Illustrative (conceptual, not a captured fixture):

User:
Why is deployment payment-api unhealthy?

Diagnosis:
health: critical
root_cause.category: REGISTRY_AUTHENTICATION_FAILURE
root_cause.confidence: high

Evidence:
- Image pull failure
- Registry authentication rejected
- Repeated FailedPull / ErrImagePull events

Recommendation:
Verify the imagePullSecret configuration.

Safety

Read-only by default. Write actions require KUBE_SRE_MCP_ACTIONS_ENABLED=true.

The server requires a confirmation token before executing guarded actions. MCP hosts should obtain explicit human approval before submitting that token.

Security · Safe actions · RBAC · Vulnerability reporting

Getting Started

Go is not required when using a prebuilt GitHub Release archive. You need a reachable Kubernetes API, a local kubeconfig, and an MCP client that can spawn a local stdio process.

Uses KUBECONFIG if set, otherwise ~/.kube/config. Optional KUBE_SRE_MCP_CONTEXT; otherwise the kubeconfig current-context.

Linux and macOS

Install into $HOME/.local/bin so sudo is not required. Choose the archive that matches your OS and CPU. The commands below use linux_amd64; substitute linux_arm64, darwin_amd64, or darwin_arm64 as needed.

kube-sre-mcp_${VERSION}_linux_amd64.tar.gz
kube-sre-mcp_${VERSION}_linux_arm64.tar.gz
kube-sre-mcp_${VERSION}_darwin_amd64.tar.gz
kube-sre-mcp_${VERSION}_darwin_arm64.tar.gz
kube-sre-mcp_${VERSION}_windows_amd64.zip

Verify the SHA256 checksum from checksums.txt before extracting or installing the binary.

VERSION=0.1.0
ARCHIVE="kube-sre-mcp_${VERSION}_linux_amd64.tar.gz"
BASE_URL="https://github.com/ielyaakouby/kube-sre-mcp/releases/download/v${VERSION}"

wget "${BASE_URL}/${ARCHIVE}"
wget "${BASE_URL}/checksums.txt"

if command -v sha256sum >/dev/null 2>&1; then
  grep -F "${ARCHIVE}" checksums.txt | sha256sum -c -
else
  grep -F "${ARCHIVE}" checksums.txt | shasum -a 256 -c -
fi

tar -xzf "${ARCHIVE}"

mkdir -p "$HOME/.local/bin"

mv kube-sre-mcp "$HOME/.local/bin/kube-sre-mcp"

chmod +x "$HOME/.local/bin/kube-sre-mcp"

Ensure $HOME/.local/bin is on PATH in the current session:

export PATH="$HOME/.local/bin:$PATH"

To keep that for new terminals, append the same line to the config file for your shell (~/.bashrc for bash, ~/.zshrc for zsh)—do not add both unless you use both shells:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Validate:

kube-sre-mcp --version
kube-sre-mcp --help

Windows uses a ZIP, not this Unix path. See docs/windows.md.

Build from source

Go 1.26.6+ (see go.mod):

git clone https://github.com/ielyaakouby/kube-sre-mcp.git
cd kube-sre-mcp
make build
./bin/kube-sre-mcp --help

MCP Client Setup

Claude and other MCP hosts that can spawn a local stdio process can use the same configuration. After the Getting Started install, the Unix binary is $HOME/.local/bin/kube-sre-mcp in a shell. MCP clients typically do not run through a shell and do not expand $HOME, so command must be a real absolute filesystem path.

KUBE_SRE_MCP_ACTIONS_ENABLED=false keeps the server read-only. Setting it to true enables only the guarded write tools (restart, scale, delete Pod, cordon/uncordon), not generic Kubernetes CRUD. See Safety.

Linux:

{
  "mcpServers": {
    "kube-sre-mcp": {
      "command": "/home/USERNAME/.local/bin/kube-sre-mcp",
      "env": {
        "KUBECONFIG": "/home/USERNAME/.kube/config",
        "KUBE_SRE_MCP_ACTIONS_ENABLED": "false"
      }
    }
  }
}

macOS:

{
  "mcpServers": {
    "kube-sre-mcp": {
      "command": "/Users/USERNAME/.local/bin/kube-sre-mcp",
      "env": {
        "KUBECONFIG": "/Users/USERNAME/.kube/config",
        "KUBE_SRE_MCP_ACTIONS_ENABLED": "false"
      }
    }
  }
}

Replace USERNAME with your account name.

Windows

For Windows installation and MCP client configuration, see docs/windows.md.

Documentation

• Documentation index
• MCP tool catalog
• Architecture
• Diagnostic engine
• Security
• Configuration
• Troubleshooting

Contributing

See CONTRIBUTING.md. Open a pull request against main after make check. For substantial changes, open an issue first.

Security

Report vulnerabilities privately. Do not open a public GitHub issue. See SECURITY.md.

License

Kube SRE MCP is licensed under the Apache License 2.0.

Copyright 2026 The Kube SRE MCP Authors.