arnstarn/mcp-server-spotinst

PyPI version CI License: MIT Python 3.10+

MCP server for the Spot.io (Spotinst) 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

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

Install with pip

pip install mcp-server-spotinst

Install with uvx (no install needed)

uvx mcp-server-spotinst

Claude Code Config

Add to ~/.mcp.json:

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

Docker

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

Run Standalone

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 at https://api.spotinst.io.