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__*",
      "mcp__plugin_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:

Code

Copy

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.