KubeStellar MCP

kubestellar-mcp

AI-powered multi-cluster Kubernetes tools for Claude Code.

Single-cluster UX for multi-cluster reality - work with your apps, not your clusters.

Why KubeStellar

kubestellar-mcp is the AI entry point to the KubeStellar platform — a CNCF Sandbox ecosystem for multi-cluster Kubernetes orchestration.

kubestellar-mcp lets AI agents inspect and operate clusters through natural language. For visual dashboards and AI missions, see KubeStellar Console.

Components

Documentation

Additional documentation lives in docs/:

• docs/index.md - expanded setup, plugin workflow, CLI usage, and operational guidance
• docs/ARCHITECTURE.md - architecture overview and contributor guide for the two MCP servers, request lifecycle, and how to add new tools

If you are contributing new MCP capabilities, start with docs/ARCHITECTURE.md; it is the best guide to how the servers are organized and where new tools should be added.

Operations

• docs/slo.md - Service Level Objectives and Indicators
• docs/alerts/ - importable Prometheus alert rules aligned with the SLOs
• docs/dashboards/ - importable Grafana dashboard
• runbooks/ - operational runbooks (startup/shutdown, cluster discovery failures, credential rotation, connectivity loss, release rollback)
• docs/postmortem-template.md - incident postmortem template
• docs/severity-levels.md - P1-P4 incident severity scale used by the incident template and postmortem requirement

Installation

Homebrew (Recommended)

brew tap kubestellar/tap

Install diagnostics tools

brew install kubestellar-ops

Install deployment tools

brew install kubestellar-deploy

Or install both

brew install kubestellar-ops kubestellar-deploy

From Releases

Download from GitHub Releases.

From Source

Prerequisites: Go 1.26+ (go version to verify)

git clone https://github.com/kubestellar/kubestellar-mcp.git

cd kubestellar-mcp

Build both binaries

go build -o bin/kubestellar-ops ./cmd/kubestellar-ops go build -o bin/kubestellar-deploy ./cmd/kubestellar-deploy

sudo mv bin/kubestellar-* /usr/local/bin/

Claude Code Plugins

Step 1: Add the KubeStellar Marketplace

In Claude Code, run:

/plugin marketplace add kubestellar/claude-plugins

Step 2: Install the Plugins

/plugin install kubestellar-ops

/plugin install kubestellar-deploy

Or:

1. Go to /plugin → Marketplaces tab → click Update on kubestellar marketplace
2. Go to /plugin → Discover tab → Install kubestellar-ops and/or kubestellar-deploy

Step 3: Verify

Run /mcp in Claude Code - you should see:

plugin:kubestellar-ops:kubestellar-ops · ✓ connected

plugin:kubestellar-deploy:kubestellar-deploy · ✓ connected

Allow Tools Without Prompts

Add to ~/.claude/settings.json:

{

"permissions": { "allow": [ "mcp__plugin_kubestellar-ops_kubestellar-ops*", "mcpplugin_kubestellar-deploy_kubestellar-deploy__*" ] } }

Or run in Claude Code:

/allowed-tools add mcp__plugin_kubestellar-ops_kubestellar-ops__*

/allowed-tools add mcp__plugin_kubestellar-deploy_kubestellar-deploy__*

Other AI Clients (VS Code, Cursor, Windsurf)

You can run either binary as a generic MCP stdio server with kubestellar-ops --mcp-server or kubestellar-deploy --mcp-server. Any MCP-compatible client can use the binary over stdio.

VS Code (GitHub Copilot)

Create .vscode/mcp.json:

{

"servers": { "kubestellar-ops": { "command": "kubestellar-ops", "args": ["--mcp-server"] } } }

Cursor

Create .cursor/mcp.json:

{

"mcpServers": { "kubestellar-ops": { "command": "kubestellar-ops", "args": ["--mcp-server"] } } }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "kubestellar-ops": { "command": "kubestellar-ops", "args": ["--mcp-server"] } } }

OpenCode

OpenCode is an open-source AI coding agent. Add the following to your project's opencode.json or opencode.jsonc:

{

"$schema": "https://opencode.ai/config.json", "mcp": { "kubestellar-ops": { "type": "local", "command": ["kubestellar-ops", "--mcp-server"], "enabled": true }, "kubestellar-deploy": { "type": "local", "command": ["kubestellar-deploy", "--mcp-server"], "enabled": true } } }

After adding, run opencode mcp list and verify both servers show as connected.

For your AI agent — Copy and paste this message into your OpenCode session to have it configure the MCP tools automatically:

`

Install kubestellar-ops and kubestellar-deploy:

# macOS — Homebrew

brew tap kubestellar/tap

brew install kubestellar-ops kubestellar-deploy

# Linux — download from GitHub Releases

curl -LO https://github.com/kubestellar/kubestellar-mcp/releases/latest/download/kubestellar-ops_linux_amd64.tar.gz

curl -LO https://github.com/kubestellar/kubestellar-mcp/releases/latest/download/kubestellar-deploy_linux_amd64.tar.gz

tar xzf kubestellar-ops_linux_amd64.tar.gz

tar xzf kubestellar-deploy_linux_amd64.tar.gz

sudo mv kubestellar-ops kubestellar-deploy /usr/local/bin/

# Or build from source (any OS, requires Go 1.26+)

git clone https://github.com/kubestellar/kubestellar-mcp.git

cd kubestellar-mcp

go build -o /usr/local/bin/kubestellar-ops ./cmd/kubestellar-ops

go build -o /usr/local/bin/kubestellar-deploy ./cmd/kubestellar-deploy

Then create opencode.jsonc in the project root with:

{

"$schema": "https://opencode.ai/config.json",

"mcp": {

"kubestellar-ops": {

"type": "local",

"command": ["kubestellar-ops", "--mcp-server"],

"enabled": true

},

"kubestellar-deploy": {

"type": "local",

"command": ["kubestellar-deploy", "--mcp-server"],

"enabled": true

}

}

}

Verify with: opencode mcp list

`

Generic MCP Client (stdio)

kubestellar-ops --mcp-server

kubestellar-deploy --mcp-server

Kubernetes RBAC

The MCP binaries use your active kubeconfig by default. If you run them in-cluster, bind the same permissions to the pod ServiceAccount.

Example read-only ClusterRole:

apiVersion: rbac.authorization.k8s.io/v1

kind: ClusterRole metadata: name: kubestellar-mcp-readonly rules:

• apiGroups: [""] resources: ["namespaces", "nodes", "pods", "pods/log", "services", "endpoints", "events", "resourcequotas", "limitranges"] verbs: ["get", "list", "watch"]
• apiGroups: ["apps", "batch"] resources: ["deployments", "replicasets", "statefulsets", "daemonsets", "jobs", "cronjobs"] verbs: ["get", "list", "watch"]
• apiGroups: ["rbac.authorization.k8s.io"] resources: ["roles", "rolebindings", "clusterroles", "clusterrolebindings"] verbs: ["get", "list", "watch"]

For write workflows, add create, update, patch, and delete to the resource rules you actually need.

Troubleshooting

Plugin not showing

• Restart Claude Code, VS Code, Cursor, or Windsurf after installing or upgrading the binary.
• Verify the binary is on your PATH with which kubestellar-ops.
• If it is not found, reinstall it or move it into a directory already on your PATH.

Permission / RBAC errors

• Run kubectl auth can-i --list to see what your current identity can access.
• Compare the output with the permissions described in the Kubernetes RBAC section above.
• If needed, update your Role, ClusterRole, or binding before retrying the MCP client.

kubeconfig problems

• Confirm the active context with kubectl config current-context.
• Check whether KUBECONFIG is set and points to the kubeconfig file you expect.
• If the wrong cluster is selected, switch contexts or update the environment variable and retry.

Manual smoke test

• You can verify the MCP server starts without opening an AI client.
• Run the initialize request below and confirm you get a JSON-RPC response back.

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | ./bin/kubestellar-ops --mcp-server

Updating

Update the CLI tools via Homebrew:

brew update

brew upgrade kubestellar-ops kubestellar-deploy

Update the plugins in Claude Code:

/plugin update kubestellar-ops

/plugin update kubestellar-deploy

---

kubestellar-ops

Multi-cluster Kubernetes diagnostics, RBAC analysis, and security checks.

Example Usage

• "List my Kubernetes clusters"
• "Find pods with issues across all clusters"
• "Check for security misconfigurations"
• "What permissions does the admin service account have?"
• "Show me warning events in kube-system"

Features

Slash Commands

---

kubestellar-deploy

App-centric multi-cluster deployment and operations.

Example Usage