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.

Using KubeStellar Console? These plugins power the Console’s cluster connectivity. See the Console Installation Guide for how they fit together.

Components

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

Quick Start

1. Install the Binaries

# Install via Homebrew
brew tap kubestellar/tap
brew install kubestellar-ops kubestellar-deploy
 
# Or install individually
brew install kubestellar-ops      # Diagnostics only
brew install kubestellar-deploy   # Deployment only

2. Install the Claude Code Plugins

/plugin marketplace add kubestellar/claude-plugins

Then go to /plugin → Marketplaces tab → click Update on kubestellar marketplace.

Go to /plugin → Discover tab and install:

kubestellar-ops - for diagnostics, RBAC, security
kubestellar-deploy - for deployment, GitOps

3. Verify Installation

Run /mcp in Claude Code - you should see:

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

4. Start Using

Ask Claude:

“List my Kubernetes clusters”
“Find pods with issues”
“Where is nginx running?”
“Check for security misconfigurations”

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

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 Plugin Setup

Adding the Marketplace

In Claude Code, run:

/plugin marketplace add kubestellar/claude-plugins

Go to /plugin → Marketplaces tab
Click Update on the kubestellar marketplace to refresh the plugin list

Installing Plugins

Go to /plugin → Discover tab
Search for “kubestellar” or browse the list
Select and install:
- kubestellar-ops - Multi-cluster diagnostics, RBAC analysis, security checks
- kubestellar-deploy - App-centric deployment, GitOps, smart workload placement
The plugins will automatically connect to the installed binaries

Verifying Connection

Run /mcp in Claude Code to see connected MCP servers:

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

If a plugin shows disconnected, ensure the binary is installed and in your PATH:

which kubestellar-ops
which kubestellar-deploy

Allow Tools Without Prompts

To avoid permission prompts for each tool call, 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__*

Troubleshooting

Plugins not showing in Discover tab:

Go to /plugin → Marketplaces tab
Click Update on the kubestellar marketplace
Return to Discover tab and search again

Plugin shows disconnected:

Verify binary is installed: which kubestellar-ops
Verify binary works: kubestellar-ops version
Restart Claude Code

Marketplace not found:

/plugin marketplace remove kubestellar
/plugin marketplace add kubestellar/claude-plugins

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”
“Analyze the default namespace”

Tools

Cluster Management

Tool	Description
`list_clusters`	Discover clusters from kubeconfig
`get_cluster_health`	Check cluster health status
`get_nodes`	List cluster nodes with status
`audit_kubeconfig`	Audit all clusters for connectivity and recommend cleanup

Workload Tools

Tool	Description
`get_pods`	List pods with filtering options
`get_deployments`	List deployments
`get_services`	List services
`get_events`	Get recent events
`describe_pod`	Get detailed pod information
`get_pod_logs`	Retrieve pod logs

RBAC Analysis

Tool	Description
`get_roles`	List Roles in a namespace
`get_cluster_roles`	List ClusterRoles
`get_role_bindings`	List RoleBindings
`get_cluster_role_bindings`	List ClusterRoleBindings
`can_i`	Check if you can perform an action
`analyze_subject_permissions`	Full RBAC analysis for any subject
`describe_role`	Detailed view of Role/ClusterRole rules

Diagnostic Tools

Tool	Description
`find_pod_issues`	Find CrashLoopBackOff, ImagePullBackOff, OOMKilled, pending pods
`find_deployment_issues`	Find stuck rollouts, unavailable replicas, ReplicaSet errors
`check_resource_limits`	Find pods without CPU/memory limits
`check_security_issues`	Find privileged containers, root users, host network
`analyze_namespace`	Comprehensive namespace analysis
`get_warning_events`	Get Warning events
`find_resource_owners`	Find who owns/manages resources

OPA Gatekeeper Policy Tools

Tool	Description
`check_gatekeeper`	Check if OPA Gatekeeper is installed and healthy
`get_ownership_policy_status`	Get ownership policy configuration and violation count
`list_ownership_violations`	List resources missing required ownership labels
`install_ownership_policy`	Install ownership labels policy (dryrun/warn/enforce modes)
`set_ownership_policy_mode`	Change policy enforcement mode
`uninstall_ownership_policy`	Remove the ownership policy

Upgrade Tools

Tool	Description
`detect_cluster_type`	Detect cluster distribution (OpenShift, EKS, GKE, AKS, kubeadm, k3s, kind)
`get_cluster_version_info`	Get current version and available upgrades
`check_olm_operator_upgrades`	Check OLM operators for pending upgrades
`check_helm_release_upgrades`	List Helm releases and their versions
`get_upgrade_prerequisites`	Validate upgrade readiness
`trigger_openshift_upgrade`	Trigger OpenShift cluster upgrade (requires confirmation)
`get_upgrade_status`	Monitor upgrade progress

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
`/k8s-ownership`	Manage ownership tracking with OPA Gatekeeper
`/k8s-upgrade-check`	Check for available upgrades (cluster, OLM, Helm)
`/k8s-upgrade`	Guided cluster upgrade with safety checks

Slash Command Examples

# Check health of all clusters
/k8s-health

# Find pod and deployment issues across all clusters
/k8s-issues

# Check for security misconfigurations (privileged containers, root users)
/k8s-security

# Analyze RBAC permissions for a user or service account
/k8s-rbac

# Check for available upgrades
/k8s-upgrade-check

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”

Tools

App Discovery & Status

Tool	Description
`get_app_instances`	Find all instances of an app across clusters
`get_app_status`	Unified health view (healthy/degraded/failed)
`get_app_logs`	Aggregated logs with cluster labels

Smart Deployment

Tool	Description
`deploy_app`	Deploy to clusters matching criteria (GPU, memory, labels)
`scale_app`	Scale across all clusters where app runs
`patch_app`	Apply patches everywhere at

Cluster Resources

Tool	Description
`list_cluster_capabilities`	GPU, CPU, memory per cluster
`find_clusters_for_workload`	Find clusters that can run a workload

GitOps

Tool	Description
`detect_drift`	Find clusters that diverged from git
`sync_from_git`	Apply manifests from git repository
`reconcile`	Bring clusters back in sync
`preview_changes`	Dry-run to see what would change

Helm Operations

Tool	Description
`helm_install`	Install or upgrade Helm charts to clusters
`helm_uninstall`	Uninstall Helm releases from clusters
`helm_list`	List Helm releases across clusters
`helm_rollback`	Rollback a release to a previous revision

Resource Management

Tool	Description
`delete_resource`	Delete K8s resources by kind/name
`kubectl_apply`	Apply any manifest using dynamic client

Kustomize Operations

Tool	Description
`kustomize_build`	Render kustomize output without applying
`kustomize_apply`	Build and apply kustomize to clusters
`kustomize_delete`	Build and delete kustomize resources

Labeling

Tool	Description
`add_labels`	Add labels to resources across clusters
`remove_labels`	Remove labels from resources

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
`/helm-install`	Install or upgrade Helm charts
`/helm-uninstall`	Uninstall Helm releases
`/helm-rollback`	Rollback to previous revision
`/delete`	Delete K8s resources
`/kustomize`	Build and apply kustomize configurations
`/label`	Add or remove labels from resources

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 chart to all clusters”

Installing nginx to 3 clusters...
  - prod-east: installed (v1.25.0)
  - prod-west: installed (v1.25.0)
  - staging: installed (v1.25.0)
All releases healthy

“Delete the old configmap”

Deleting ConfigMap/old-config from 3 clusters...
  - prod-east: deleted
  - prod-west: deleted
  - staging: not-found (already removed)

“Rollback redis to previous version”

Rolling back redis in 2 clusters...
  - prod-east: rolled back to revision 3
  - prod-west: rolled back to revision 3

“Apply kustomize from overlays/production”

Building kustomize from ./overlays/production...
Applying 5 resources to 3 clusters...
  - prod-east: applied (5 resources)
  - prod-west: applied (5 resources)
  - prod-central: applied (5 resources)

“Add label team=platform to deployment api”

Adding labels to Deployment/api...
  - prod-east: labeled
  - prod-west: labeled
  - staging: labeled
Labels added: team=platform

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
 
# Watch OpenShift upgrade with live progress bar
kubestellar-ops watch-upgrade
kubestellar-ops watch-upgrade --context=prod-cluster --interval=5s

Live Progress Bar

The watch-upgrade command displays a self-updating progress bar that overwrites itself:

⏳ 4.18.30 [###########---------------------------------------]  22% (200/906) cloud-controller-manager

When complete:

✅ 4.18.30 [##################################################] 100%

kubestellar-deploy

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

Environment Variables

Variable	Description
`KUBECONFIG`	Path to kubeconfig file

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

Apache License 2.0 - see LICENSE for details.