# exoscale-mcp

MCP server for the Exoscale Swiss cloud platform.

Uses a hybrid approach:
- **GET** operations hit the Exoscale v2 REST API directly with simple header auth.
- **Write** operations (create/delete/start/stop/reboot/rules) shell out to the `exo` CLI,
  which handles HMAC-SHA256 request signing correctly.

## Prerequisites

1. **Python 3.11+** and pip
2. **`exo` CLI** installed (`brew install exoscale/tap/exo` or https://community.exoscale.com/documentation/tools/exoscale-command-line-interface/)  
   and logged in (`exo config add`)
3. An Exoscale API key/secret (IAM → API keys in the console)

## Setup

```bash
cd /tmp/exoscale-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `EXOSCALE_API_KEY` | Yes | — | IAM API key (starts with `EXO`) |
| `EXOSCALE_API_SECRET` | Yes | — | IAM API secret |
| `EXOSCALE_CONFIG` | No | `~/.config/exoscale/exoscale.toml` | Path to exo CLI config file |

Copy `.env.example` to `.env` and fill in your values.

## Running standalone

```bash
source .venv/bin/activate
export EXOSCALE_API_KEY=EXO...
export EXOSCALE_API_SECRET=...
python server.py
```

## Claude Code MCP config

Add to `~/.claude/settings.json` (or `settings.local.json`):

```json
{
  "mcpServers": {
    "exoscale": {
      "command": "/tmp/exoscale-mcp/.venv/bin/python",
      "args": ["/tmp/exoscale-mcp/server.py"],
      "env": {
        "EXOSCALE_API_KEY": "EXO...",
        "EXOSCALE_API_SECRET": "...",
        "EXOSCALE_CONFIG": "/Users/you/.config/exoscale/exoscale.toml"
      }
    }
  }
}
```

## Available tools

| Tool | Method | Description |
|---|---|---|
| `list_zones` | CLI | List all Exoscale zones |
| `list_instance_types` | GET | List instance types in a zone |
| `list_templates` | GET | List OS templates in a zone |
| `list_instances` | CLI | List compute instances in a zone |
| `get_instance` | CLI | Get full details for an instance |
| `create_instance` | CLI | Create a new instance |
| `destroy_instance` | CLI | Permanently destroy an instance |
| `start_instance` | CLI | Start a stopped instance |
| `stop_instance` | CLI | Stop a running instance |
| `reboot_instance` | CLI | Reboot an instance |
| `list_ssh_keys` | CLI | List registered SSH keys |
| `create_ssh_key` | CLI | Register a new SSH public key |
| `list_security_groups` | CLI | List security groups in a zone |
| `get_security_group` | CLI | Get security group details and rules |
| `add_security_group_rule` | CLI | Add an ingress/egress firewall rule |

## Notes

- `destroy_instance` is irreversible. The CLI `--force` flag skips the confirmation prompt.
- SSH keys are global (not zone-scoped) on Exoscale.
- Security group rules support protocols: `tcp`, `udp`, `icmp`, `icmpv6`, `gre`, `esp`, `ah`, `ipip`.
- The `exo` CLI must be authenticated for the same account as the API key.