# Exoscale MCP Server

[![npm version](https://img.shields.io/npm/v/@samisouabni/exoscale-mcp)](https://www.npmjs.com/package/@samisouabni/exoscale-mcp)
[![CI](https://github.com/samisouabni/exoscale-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/samisouabni/exoscale-mcp/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Node.js](https://img.shields.io/node/v/@samisouabni/exoscale-mcp)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-v2-green)](https://modelcontextprotocol.io)
[![npm downloads](https://img.shields.io/npm/dm/@samisouabni/exoscale-mcp)](https://www.npmjs.com/package/@samisouabni/exoscale-mcp)

An MCP (Model Context Protocol) server that enables AI assistants to manage [Exoscale](https://www.exoscale.com/) cloud infrastructure. Supports both stdio and Streamable HTTP transports with read-only mode enabled by default for safety.

## Features

- **10 composite tools** covering Compute, SKS (Kubernetes), DNS, DBaaS, Block Storage, and Object Storage
- **4 read-only resources** for reference data (zones, instance types, templates, database plans)
- **Dual transport** — stdio for local use (Claude Desktop, Kiro) and HTTP for remote/shared deployments
- **Read-only by default** — write operations require explicit opt-in via `EXOSCALE_MCP_READ_ONLY=false`
- **Dry-run support** — preview any mutation before executing
- **EXO2-HMAC-SHA256 authentication** with env var and config file credential resolution

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in stdio mode (default, read-only)
EXOSCALE_API_KEY=your-key EXOSCALE_API_SECRET=your-secret npm start

# Run in HTTP mode
npm run start:http
```

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `EXOSCALE_API_KEY` | — | Exoscale API key (required) |
| `EXOSCALE_API_SECRET` | — | Exoscale API secret (required) |
| `EXOSCALE_ZONE` | `ch-gva-2` | Default API zone |
| `EXOSCALE_MCP_READ_ONLY` | `true` | Set to `false` to enable write operations |
| `EXOSCALE_MCP_TRANSPORT` | `stdio` | Transport: `stdio` or `http` |
| `EXOSCALE_MCP_PORT` | `3000` | HTTP port (when transport is `http`) |

CLI flags `--http` and `--port <n>` override the environment variables.

### Credential Resolution

1. `EXOSCALE_API_KEY` + `EXOSCALE_API_SECRET` environment variables
2. `~/.exoscale/config` file (INI format, `[default]` section)

## Safety Model

The server implements three layers of safety:

1. **Read-only mode (default ON)** — All mutations return a clear error message directing the user to set `EXOSCALE_MCP_READ_ONLY=false`
2. **Dry-run mode** — Pass `dryRun: true` to any mutating action to preview what would happen
3. **Destructive annotations** — Tools are annotated with `destructiveHint: true` so MCP clients can prompt for confirmation

## Tools

| Tool | Actions | Description |
|------|---------|-------------|
| `compute_instance` | list, get, create, start, stop, reboot, resize, delete | Manage compute VMs |
| `compute_security_group` | list, get, create, delete, add_rule, remove_rule | Manage firewall rules |
| `elastic_ip` | list, get, create, delete, attach, detach | Manage elastic IPs |
| `sks_cluster` | list, get, create, upgrade, delete, get_kubeconfig | Manage Kubernetes clusters |
| `sks_nodepool` | list, get, create, scale, delete | Manage cluster node pools |
| `dns_domain` | list, get, create, delete | Manage DNS zones |
| `dns_record` | list, get, create, update, delete | Manage DNS records |
| `dbaas_service` | list, get, create, update, delete, get_connection_info | Manage databases |
| `block_storage` | list, get, create, resize, attach, detach, snapshot, delete | Manage volumes |
| `object_storage` | list_buckets, create_bucket, delete_bucket, get_presigned_url | Manage SOS buckets |

## Resources

| URI | Description |
|-----|-------------|
| `exoscale://zones` | Available datacenter zones |
| `exoscale://instance-types` | Compute instance types (CPU, RAM, family) |
| `exoscale://templates` | OS templates for instances |
| `exoscale://dbaas-service-types` | Database service types and plans |

## MCP Client Configuration

### Kiro / Claude Desktop (stdio)

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "exoscale": {
      "command": "node",
      "args": ["/path/to/exoscale-mcp/dist/index.js"],
      "env": {
        "EXOSCALE_API_KEY": "your-key",
        "EXOSCALE_API_SECRET": "your-secret"
      }
    }
  }
}
```

### HTTP mode

```bash
EXOSCALE_API_KEY=key EXOSCALE_API_SECRET=secret node dist/index.js --http --port 3000
```

Then connect your MCP client to `http://127.0.0.1:3000/mcp`.

## Development

```bash
# Dev mode (tsx, auto-restarts not included)
npm run dev

# Type check
npm run lint

# Run tests
npm test

# Run with coverage
npm run test:coverage

# Regenerate types from OpenAPI spec
npm run generate:types
```

## Architecture

See [ARCHITECTURE.md](./ARCHITECTURE.md) for a detailed system overview.

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on adding tools, resources, and tests.

## License

Apache License 2.0 — see [LICENSE](./LICENSE) for details.