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.

Related MCP server: Kubernetes MCP Server

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:

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

• "Where is nginx running?"

• "Get logs from my api service"

• "Deploy my ML model to clusters with GPUs"

• "Are my clusters in sync with git?"

• "Scale my app to 5 replicas across all clusters"

Features

Slash Commands

Example Workflows

"Where is my app running?"

nginx is running on 3 clusters:
  - prod-east: 3 replicas, healthy
  - prod-west: 3 replicas, healthy
  - staging: 1 replica, healthy

"Deploy to GPU clusters"

Found 2 clusters with nvidia.com/gpu
Deployed to gpu-cluster-1, gpu-cluster-2
All healthy

"Check for drift"

Drift detected:
  - prod-west: ConfigMap/app-config differs
  - staging: Deployment/api has extra replicas

"Install nginx-ingress with Helm"

Installing nginx-ingress to 3 clusters...
  - prod-east: Installed nginx-ingress v1.10.0
  - prod-west: Installed nginx-ingress v1.10.0
  - staging: Installed nginx-ingress v1.10.0
All releases healthy

"Apply kustomize overlay"

Building kustomize from overlays/production...
Applied to 2 clusters:
  - prod-east: 5 resources applied
  - prod-west: 5 resources applied

"Delete the test deployment"

Deleted deployment/test from 3 clusters:
  - prod-east: deleted
  - prod-west: deleted
  - staging: deleted

CLI Usage

kubestellar-ops

# Run as MCP server (for Claude Code)
kubestellar-ops --mcp-server

# List clusters
kubestellar-ops clusters list

# Check cluster health
kubestellar-ops clusters health

kubestellar-deploy

# Run as MCP server (deployment, GitOps, Helm, kubectl, and kustomize tools)
kubestellar-deploy --mcp-server

# Show version information
kubestellar-deploy version

# Generate shell completion
kubestellar-deploy completion bash

kubestellar-deploy does not currently expose standalone deployment subcommands. Outside MCP server mode, the CLI only provides informational commands such as version, completion, and help. App deployment, GitOps, Helm, kubectl, kustomize, and labeling workflows are available through the MCP tool server started with --mcp-server. To target a different Kubernetes environment, point KUBECONFIG at the desired kubeconfig (or switch the active context in that kubeconfig) before starting the binary.

Environment Variables

Related runtime flags

kubestellar-ops also inherits the standard Kubernetes client flags from kubectl, so contributors can override cluster selection and request behavior at runtime without additional environment variables. Common examples include:

• --context to select a kubeconfig context

• --namespace to scope namespaced operations

• --request-timeout to override API request timeouts

• --cluster, --user, --server, --token, and TLS flags for advanced auth/connection overrides

• --all-clusters, --target-cluster, and --mcp-server for KubeStellar-specific behavior

kubestellar-deploy currently exposes --mcp-server as its runtime flag and does not require any additional environment variables beyond Kubernetes client configuration.

Related Projects

• KubeStellar - Multi-cluster orchestration platform

• KubeStellar Console - AI-powered web dashboard for multi-cluster management

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

Apache License 2.0 - see LICENSE for details.