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.

Sub-project	Role
kubestellar	Core engine — BindingPolicy, WDS, ITS, WEC workload propagation
console	Web dashboard — 300+ cards, AI missions, GPU and LLM-d monitoring
console-marketplace	153+ community card presets (GPU/AI/ML, ArgoCD, OPA, Falco, security)
console-kb	AI knowledge base — community missions and operational runbooks
kubestellar-mcp	This repo — MCP server for Claude, Cursor, Windsurf, VS Code

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

Components

Binary	Description
kubestellar-ops	Multi-cluster diagnostics, RBAC analysis, security checks
kubestellar-deploy	App-centric deployment, GitOps, smart workload placement

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

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:

Go to /plugin → Marketplaces tab → click Update on kubestellar marketplace
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.

Use case	Typical permissions
kubestellar-ops read-only	`get`, `list`, `watch` on namespaces, nodes, pods, pods/log, services, endpoints, deployments, replica sets, statefulsets, daemonsets, jobs, cronjobs, events, resourcequotas, limitranges, roles, rolebindings, clusterroles, and clusterrolebindings
kubestellar-deploy write	Everything above, plus `create`, `update`, `patch`, and `delete` on the resource types you plan to manage

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

Category	Tools
Cluster	`list_clusters`, `get_cluster_health`, `get_nodes`, `audit_kubeconfig`
Workloads	`get_pods`, `get_deployments`, `get_services`, `get_events`, `describe_pod`, `get_pod_logs`
RBAC	`get_roles`, `get_cluster_roles`, `get_role_bindings`, `can_i`, `analyze_subject_permissions`
Diagnostics	`find_pod_issues`, `find_deployment_issues`, `check_resource_limits`, `check_security_issues`
Gatekeeper	`check_gatekeeper`, `install_ownership_policy`, `list_ownership_violations`
Upgrades	`detect_cluster_type`, `get_cluster_version_info`, `check_helm_release_upgrades`
GitOps	`detect_drift`

Slash Commands

Command	Description
`/k8s-health`	Check health of all clusters
`/k8s-issues`	Find pod and deployment issues
`/k8s-security`	Check for security misconfigurations
`/k8s-rbac`	Analyze RBAC permissions
`/k8s-analyze`	Comprehensive namespace analysis
`/k8s-audit-kubeconfig`	Audit kubeconfig clusters and recommend cleanup
`/k8s-ownership`	Manage ownership tracking with OPA Gatekeeper
`/k8s-upgrade-check`	Check for available upgrades
`/k8s-upgrade`	Upgrade cluster (master and nodes)

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

Category	Tools
App Discovery	`get_app_instances`, `get_app_status`, `get_app_logs`
Deployment	`deploy_app`, `scale_app`, `patch_app`
Placement	`list_cluster_capabilities`, `find_clusters_for_workload`
GitOps	`sync_from_git`, `detect_drift`, `reconcile`, `preview_changes`
Helm	`helm_install`, `helm_uninstall`, `helm_list`, `helm_rollback`
Kustomize	`kustomize_build`, `kustomize_apply`, `kustomize_delete`
Resources	`kubectl_apply`, `delete_resource`
Labels	`add_labels`, `remove_labels`

Slash Commands

Command	Description
`/app-status`	Show status of an app across all clusters
`/app-logs`	Get aggregated logs from an app
`/deploy`	Deploy or update an app
`/gitops-sync`	Sync clusters from git
`/gitops-drift`	Check for drift from git

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

Variable	Used by	Description
`KUBECONFIG`	`kubestellar-ops`, `kubestellar-deploy`	Path to the kubeconfig file to use instead of the default Kubernetes client lookup path
`ANTHROPIC_API_KEY`	`kubestellar-ops`	Required for the `query` command and natural-language cluster queries backed by Claude

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.

Name		Name	Last commit message	Last commit date
.github		.github
cmd		cmd
commands		commands
docs		docs
internal/version		internal/version
pkg		pkg
runbooks		runbooks
.dockerignore		.dockerignore
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DCO		DCO
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
OWNERS		OWNERS
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SOLUTION_ISSUE_836.md		SOLUTION_ISSUE_836.md
go.mod		go.mod
go.sum		go.sum
server.json		server.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

kubestellar-mcp

Why KubeStellar

Components

Documentation

Operations

Installation

Homebrew (Recommended)

From Releases

From Source

Claude Code Plugins

Step 1: Add the KubeStellar Marketplace

Step 2: Install the Plugins

Step 3: Verify

Allow Tools Without Prompts

Other AI Clients (VS Code, Cursor, Windsurf)

VS Code (GitHub Copilot)

Cursor

Windsurf

OpenCode

Generic MCP Client (stdio)

Kubernetes RBAC

Troubleshooting

Plugin not showing

Permission / RBAC errors

kubeconfig problems

Manual smoke test

Updating

kubestellar-ops

Example Usage

Features

Slash Commands

kubestellar-deploy

Example Usage

Features

Slash Commands

Example Workflows

CLI Usage

kubestellar-ops

kubestellar-deploy

Environment Variables

Related runtime flags

Related Projects

Contributing

License

About

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages