cube-mcp 0.3.6
MCP server for EdgescaleAI Cube operations
Requires Python: >=3.10

# cube-mcp

MCP server for EdgescaleAI Cube management and Apollo deployments.

## Install

```bash
npx cube-mcp
```

Requires [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/).

## Add to Claude Code

```bash
claude mcp add cube -- npx cube-mcp
```

## Tools

### Setup

| Tool | Description |
|------|-------------|
| `setup_check` | Check all prerequisites and show status |
| `setup_install_teleport` | Install Teleport CLI (tsh) |
| `setup_install_kubectl` | Install kubectl |
| `setup_install_helm` | Install Helm |
| `setup_install_docker` | Install Docker |
| `setup_install_apollo` | Guide for Apollo CLI installation |
| `setup_configure_credentials` | Configure Apollo credentials |

### Cube Management

| Tool | Description |
|------|-------------|
| `cube_login` | Login to a Cube (guided - shows SSO and password options) |
| `cube_login_password` | Login via username/password (guided) |
| `cube_list` | List available Cubes |
| `cube_status` | Get Cube node status |

### App Proxy

| Tool | Description |
|------|-------------|
| `app_list` | List available Teleport apps (HTTP/TCP) |
| `app_login` | Login to a Teleport app |
| `app_proxy` | Start local proxy for an app (MQTT, databases, etc.) |
| `app_proxy_stop` | Stop running app proxies |
| `app_proxy_status` | Show status of running proxies |

### Apollo Deployments

| Tool | Description |
|------|-------------|
| `build_and_publish_to_apollo` | Build and publish app to Apollo |
| `acr_login` | Login to Apollo Container Registry |
| `acr_get_token` | Get ACR OAuth token |
| `create_environment` | Create a new Apollo environment with control plane module |
| `replicate_environment` | Clone an environment (modules, entities, configs, secrets) |
| `install_entity` | Install a Helm chart entity on an environment |
| `list_environments` | List Apollo environments (optionally filter by name) |
| `entity_health` | Get health/activity status of entities in an environment |
| `plan_details` | Deep-dive into entity plan details (tasks, events, error logs) |

## Quick Start

```
You: "Check my setup"
You: "Install kubectl"
You: "Connect me to staging-int"
You: "What's the Cube status?"
You: "List available apps"
You: "Proxy mosquitto-dev so I can connect locally"
You: "Build and publish my app"
You: "Create a new environment called my-test"
You: "Replicate pep-onlogicmc610-6 into a new env called pep-clone"
You: "List my Apollo environments"
You: "Show entity health for staging-int"
You: "Why did the dozzle install fail on pep-4?"
You: "Show plan details for redpanda-connect-20 on pep-4"
```

## Credentials

### Teleport

Login is guided - the tool will show you the commands to run:
- **Okta SSO**: `tsh login --proxy=edgescaleai.teleport.sh --auth=okta`
- **Username/Password**: `tsh login --proxy=edgescaleai.teleport.sh --user=<username>`

### Apollo

Either method works — the MCP server checks both:

**Option 1: apollo-cli configure (recommended)**

```bash
apollo-cli configure
```

This stores credentials in your apollo-cli profile. The MCP server reads them automatically.

**Option 2: Environment variables**

```bash
export APOLLO_CLIENT="<your-client-id>"
export APOLLO_SECRET="<your-client-secret>"
```

Add to `~/.bashrc` or `~/.zshrc` and restart your terminal.

## Local Development

### First-time setup

```bash
# Clone the repo
git clone https://github.com/EdgescaleAI/cube-mcp.git
cd cube-mcp

# Create virtual environment and install
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Add to Claude Code (use full path to venv python)
claude mcp add cube-local -- $(pwd)/.venv/bin/python -m cube_mcp.server
```

### Reload after code changes

In Claude Code, run:

```
/mcp
```

This reloads all MCP servers and picks up your latest code changes.

### Run server directly (for debugging)

```bash
source .venv/bin/activate
python -m cube_mcp.server
```

## Documentation

See [docs.md](docs.md) for detailed tool parameters and usage examples.

## Contributing

1. Create a branch
2. Make changes
3. Test locally with `/mcp` reload
4. Push and create PR
5. Merge to main → auto-publishes to PyPI and npm