Content
# mcp-server-spotinst
[](https://pypi.org/project/mcp-server-spotinst/)
[](https://github.com/arnstarn/mcp-server-spotinst/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](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`.
