RootCause 🧭

RootCause is a local-first MCP server that helps operators manage Kubernetes resources and identify the real root cause of failures through interoperable toolsets.

Built in Go for a fast, single-binary workflow that competes with npx-based MCP servers while staying kubeconfig-native. ⚡

Mission statement: “RootCause is a local-first MCP server that helps operators manage Kubernetes resources and identify the real root cause of failures through interoperable toolsets.”

Inspired by:
- https://github.com/containers/kubernetes-mcp-server
- https://github.com/Flux159/mcp-server-kubernetes

---

Contents

- Why RootCause
- Quick Start
- Installation
- Usage
- MCP Client Example (stdio)
- MCP Client Setup
- Toolchains
- Tools
- Safety Modes
- Config and Flags
- Kubeconfig Resolution
- Architecture Overview
- MCP Transport
- Future Cloud Readiness
- Collaboration
- Development

---

Why RootCause

- Local-first: Uses your kubeconfig identity only. No API keys required.
- Interoperable toolchains: K8s, Linkerd, Istio, and Karpenter share the same clients, evidence, and render logic.
- Fast and portable: One static Go binary, stdio-first MCP transport.
- Competitive by design: Go binary speed and distribution with parity vs npx-based MCP servers.
- Debugging built-in: Structured reasoning with likely root causes, evidence, and next checks.
- Plugin-ready: Clean SDK to add toolchains without duplicating K8s logic.
- ⭐ Like it? Star the repo to help us grow and keep shipping.

Quick Start 🚀

1) Run the server:

go run ./cmd/rootcause --config config.example.toml

2) Use your existing kubeconfig (default) or point to one:

- Uses KUBECONFIG if set, otherwise ~/.kube/config.
- Override with --kubeconfig and --context.

3) Connect your MCP client using stdio.

RootCause is built for local development. No API keys are required in this version.

---

Installation

Homebrew:

brew install yindia/homebrew-yindia/rootcause

Curl install:

curl -fsSL https://raw.githubusercontent.com/yindia/rootcause/refs/heads/main/install.sh | sh

Go install:

go install ./cmd/rootcause

Or build a local binary:

go build -o rootcause ./cmd/rootcause

Supported OS: macOS, Linux, and Windows.

Windows build example:

go build -o rootcause.exe ./cmd/rootcause

---

Usage

Run with a config file:

rootcause --config config.toml

Enable a subset of toolchains:

rootcause --toolsets k8s,istio

Enable read-only mode:

rootcause --read-only

---

MCP Client Example (stdio)

rootcause --config config.toml

Point your MCP client to run the command above and use stdio transport.

---

MCP Client Setup

All MCP clients need the same three fields:
- command: the RootCause binary
- args: CLI flags (--config, --toolsets, etc.)
- env: optional environment variables like KUBECONFIG

Codex CLI

Add an MCP server entry pointing to RootCause (format varies by client version). Example:

[mcp.servers.rootcause]
command = "rootcause"
args = ["--config", "/path/to/config.toml"]
env = { KUBECONFIG = "/path/to/kubeconfig" }

Claude Desktop

Add RootCause to the MCP servers section (use your local config path). Example:

{
  "mcpServers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/path/to/config.toml"],
      "env": { "KUBECONFIG": "/path/to/kubeconfig" }
    }
  }
}

GitHub Copilot (VS Code)

If your Copilot/VS Code build supports MCP servers, add a server entry with the RootCause command. Example:

"mcp.servers": {
  "rootcause": {
    "command": "rootcause",
    "args": ["--config", "/path/to/config.toml"],
    "env": { "KUBECONFIG": "/path/to/kubeconfig" }
  }
}

If the MCP settings key differs in your client, map the fields above to its configuration format.

---

Toolchains

Enabled by default:
- k8s
- linkerd
- karpenter
- istio
- helm
- aws

Optional toolchains return “not detected” when the control plane is absent. Additional toolchains can be registered via the plugin SDK; see PLUGINS.md.

---

Tools

See TOOLS.md for the full tool catalog, quick picker, and graph-first debugging flow references.

---

Safety Modes

- --read-only: removes apply/patch/delete/exec tools from discovery.
- --disable-destructive: removes delete and risky write tools unless allowlisted (create/scale/rollout remain available).

---

Config and Flags

rootcause --config config.example.toml --toolsets k8s,linkerd,istio,karpenter,helm,aws

Flags

- --kubeconfig
- --context
- --toolsets (comma-separated)
- --config
- --read-only
- --disable-destructive
- --log-level

If --config is not set, RootCause will use the ROOTCAUSE_CONFIG environment variable when present.

---

AWS Credentials

The AWS IAM tools use the standard AWS credential chain and region resolution. Set AWS_REGION or AWS_DEFAULT_REGION (defaults to us-east-1), optionally select a profile with AWS_PROFILE or AWS_DEFAULT_PROFILE, and use any of the normal credential sources (env vars, shared config/credentials files, SSO, or instance metadata).

---

Kubeconfig Resolution

If --kubeconfig is not set, RootCause follows standard Kubernetes loading rules: it uses KUBECONFIG when present, otherwise defaults to ~/.kube/config.

Authentication and authorization use your kubeconfig identity only in this version.

---

Architecture Overview

RootCause is organized around shared Kubernetes plumbing and toolsets that reuse it.

- Shared clients (typed, dynamic, discovery, RESTMapper) are created once in internal/kube and injected into all toolsets.
- Common safeguards live in internal/policy (namespace vs cluster enforcement and tool allowlists) and internal/redact (token/secret redaction).
- internal/evidence gathers events, owner chains, endpoints, and pod status summaries used by all toolsets.
- internal/render enforces a consistent analysis output format (root causes, evidence, next checks, resources examined) and provides the shared describe helper.
- Toolsets live under toolsets/ and register namespaced tools (k8s., linkerd., karpenter., istio., helm., aws.iam., aws.vpc.*) through a shared MCP registry.

The MCP server runs over stdio using the MCP Go SDK and is designed for local kubeconfig usage. Optional in-cluster deployment is intentionally out of scope for Phase 1.

Config Reload

Send SIGHUP to reload config and rebuild the tool registry.
On Windows, SIGHUP is not supported; restart the process to reload config.

---

MCP Transport

RootCause uses MCP over stdio by default (required). HTTP/SSE is not implemented in Phase 1.

---

Future Cloud Readiness

AWS IAM support is now available. The toolset system is designed to add deeper cloud integrations (EKS/EC2/VPC/GCP/Azure) without changing the core MCP or shared Kubernetes libraries.

---

Collaboration 🤝

We welcome collaborators, reviewers, and plugin authors. If you want to add toolsets, improve heuristics, or build cloud integrations, open an issue or PR. Help us make RootCause the fastest, most interoperable Kubernetes MCP server in the ecosystem.

---

Development

- Config example: config.toml
- Plugin SDK guide: PLUGINS.md

Run unit tests:

go test ./...