# mcp-server-spotinst

[![PyPI version](https://img.shields.io/pypi/v/mcp-server-spotinst)](https://pypi.org/project/mcp-server-spotinst/)
[![CI](https://github.com/arnstarn/mcp-server-spotinst/actions/workflows/ci.yml/badge.svg)](https://github.com/arnstarn/mcp-server-spotinst/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

MCP server for the [Spot.io (Spotinst)](https://spot.io/) API. Supports both AWS and Azure Ocean clusters with multi-account access.

## Tools (34)

### Cross-Account

| Tool | Description |
|------|-------------|
| `list_accounts` | List all Spotinst accounts accessible with the current token |
| `list_all_clusters` | List ALL clusters across ALL accounts and clouds (AWS + Azure) |

### AWS Ocean

| Tool | Description |
|------|-------------|
| `list_clusters` | List AWS Ocean K8s clusters |
| `get_cluster` | Get AWS Ocean cluster details |
| `list_vngs` | List AWS Virtual Node Groups (launch specs) |
| `get_vng` | Get AWS VNG details |
| `list_elastigroups` | List all Elastigroups |
| `get_elastigroup` | Get Elastigroup details |
| `get_allowed_instance_types` | Get allowed EC2 instance types |
| `get_right_sizing` | Get right-sizing resource suggestions (AWS only) |

### Azure Ocean

| Tool | Description |
|------|-------------|
| `list_clusters_azure` | List Azure Ocean clusters |
| `get_cluster_azure` | Get Azure Ocean cluster details |
| `list_vngs_azure` | List Azure Virtual Node Groups |
| `get_vng_azure` | Get Azure VNG details |

### Both Clouds (pass `cloud="azure"` for Azure)

| Tool | Description |
|------|-------------|
| `get_cluster_nodes` | List nodes in an Ocean cluster |
| `get_cluster_costs` | Get aggregated cost breakdown by namespace or resource |
| `list_rolls` | List deployment rolls |
| `get_roll` | Get roll details |
| `get_cluster_log` | Get scaling and activity log events |

### Stateful Nodes (AWS Managed Instances)

| Tool | Description |
|------|-------------|
| `list_stateful_nodes` | List all Stateful Nodes (Managed Instances) |
| `get_stateful_node` | Get Stateful Node details |

### Scheduling & Health

| Tool | Description |
|------|-------------|
| `get_cluster_scheduling` | Get scheduling and auto-scaler configuration |
| `get_cluster_health` | Composite health check: nodes, recent errors, active rolls |

### Cost Analysis

| Tool | Description |
|------|-------------|
| `get_cost_trending` | Week-over-week (or custom period) cost comparison |
| `get_savings_summary` | 30-day cost and savings summary |

### Tag Filtering

| Tool | Description |
|------|-------------|
| `filter_clusters_by_tag` | Filter clusters by tag key/value |
| `filter_vngs_by_tag` | Filter VNGs by tag key/value |

### Export (YAML)

| Tool | Description |
|------|-------------|
| `export_cluster_yaml` | Export cluster config as YAML for GitOps/backup |
| `export_vng_yaml` | Export VNG config as YAML for GitOps/backup |

### Write Operations (require `confirm=true`)

| Tool | Description |
|------|-------------|
| `remove_instances` | **Recommended** — Remove instances using a named strategy (see below) |
| `initiate_roll` | Rolling restart of nodes in an Ocean cluster |
| `detach_instances` | Detach and optionally terminate instances from an AWS Ocean cluster |
| `update_vng` | Update an AWS VNG configuration |
| `update_vng_azure` | Update an Azure VNG configuration |

All tools accept an optional `account_id` parameter to query any account.

### Instance Removal Strategies

The `remove_instances` tool provides a safe, intent-based interface for removing instances. Instead of remembering which API flags to set, you pick a strategy:

| Strategy | What happens | Use case |
|----------|-------------|----------|
| `drain_and_replace` | Gracefully drain pods (respects PDBs), terminate, Ocean replaces. **Default and safest.** | Replacing a problematic node in production |
| `replace` | Immediately terminate, Ocean auto-replaces. No graceful drain. AWS only. | Fast replacement when drain isn't needed |
| `remove_permanently` | Terminate + reduce cluster capacity. No replacement. AWS only. | Downsizing the cluster |

When `confirm=false` (default), the tool shows a detailed execution plan so you can review before proceeding:

```
remove_instances("o-abc123", "i-abc123", strategy="drain_and_replace")

→ SAFETY: Action NOT executed. Set confirm=true to proceed.
  DRAIN AND REPLACE 1 instance(s) in cluster o-abc123:
    Instances: ['i-abc123']
    Method: Rolling restart (20% per batch)
    - Pods will be gracefully drained (PDBs respected)
    - Instances will be terminated after drain
    - Ocean will automatically launch replacements
```

## Setup

### Environment Variables

```bash
export SPOTINST_TOKEN="your-spotinst-api-token"
export SPOTINST_ACCOUNT_ID="act-xxxxxxxx"
```

### Install with pip

```bash
pip install mcp-server-spotinst
```

### Install with uvx (no install needed)

```bash
uvx mcp-server-spotinst
```

### Claude Code Config

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "spotinst": {
      "command": "uvx",
      "args": ["mcp-server-spotinst"],
      "env": {
        "SPOTINST_TOKEN": "your-token",
        "SPOTINST_ACCOUNT_ID": "act-xxxxxxxx"
      }
    }
  }
}
```

### Docker

```bash
docker build -t mcp-server-spotinst .
docker run -e SPOTINST_TOKEN=your-token -e SPOTINST_ACCOUNT_ID=act-xxxxxxxx mcp-server-spotinst
```

### Run Standalone

```bash
mcp-server-spotinst
```

## Multi-Account Usage

Your personal API token can access multiple Spotinst accounts. Use `list_accounts` to see all available accounts, then pass `account_id` to any tool:

```
list_clusters(account_id="act-be5e7ffe")
get_cluster_nodes("o-390ef886", account_id="act-9785011e", cloud="azure")
```

Or use `list_all_clusters` for a single-call inventory across everything.

## API Reference

Uses the [Spot.io REST API](https://docs.spot.io/api/) at `https://api.spotinst.io`.