---
title: Introduction
description: AI-powered multi-cluster Kubernetes tools for Claude Code
---

# 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](../../console/installation.md) 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

```bash
# 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

```text
/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:

```yaml
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)

```bash
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](https://github.com/kubestellar/kubestellar-mcp/releases).

### From Source

```bash
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

1. In Claude Code, run:
   
   ```text
   /plugin marketplace add kubestellar/claude-plugins
   ```

2. Go to `/plugin` → **Marketplaces** tab

3. Click **Update** on the kubestellar marketplace to refresh the plugin list

### Installing Plugins

1. Go to `/plugin` → **Discover** tab

2. Search for "kubestellar" or browse the list

3. Select and install:
   - **kubestellar-ops** - Multi-cluster diagnostics, RBAC analysis, security checks
   - **kubestellar-deploy** - App-centric deployment, GitOps, smart workload placement

4. The plugins will automatically connect to the installed binaries

### Verifying Connection

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

```yaml
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:

```bash
which kubestellar-ops
which kubestellar-deploy
```

### Allow Tools Without Prompts

To avoid permission prompts for each tool call, add to `~/.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "mcp__plugin_kubestellar-ops_kubestellar-ops__*",
      "mcp__plugin_kubestellar-deploy_kubestellar-deploy__*"
    ]
  }
}
```

Or run in Claude Code:

```text
/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:**
1. Go to `/plugin` → **Marketplaces** tab
2. Click **Update** on the kubestellar marketplace
3. Return to **Discover** tab and search again

**Plugin shows disconnected:**
1. Verify binary is installed: `which kubestellar-ops`
2. Verify binary works: `kubestellar-ops version`
3. Restart Claude Code

**Marketplace not found:**

```text
/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 only 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

```bash
# 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 once |

#### 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?"**

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

**"Deploy to GPU clusters"**

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

**"Check for drift"**

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

**"Install nginx chart to all clusters"**

```text
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"**

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

**"Rollback redis to previous version"**

```text
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"**

```text
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"**

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

---

## CLI Usage

### kubestellar-ops

```bash
# 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:

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

When complete:

```text
✅ 4.18.30 [##################################################] 100%
```

### kubestellar-deploy

```bash
# 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](https://github.com/kubestellar/kubestellar-mcp/blob/main/CONTRIBUTING.md).

## License

Apache License 2.0 - see [LICENSE](https://github.com/kubestellar/kubestellar-mcp/blob/main/LICENSE) for details.
