[SPOTICKER]

// MCP Integration

Spoticker MCP Server

>_ Three tools for any MCP-compatible agent harness. get_spot_prices queries live GPU spot prices across AWS, Azure, GCP, RunPod, CoreWeave, and Nebius. get_spot_placement_score hits the EC2 API for real-time 1–10 availability scores per region. analyze_workload runs a 5-stage pipeline to turn your Dockerfile, k8s manifest, or Terraform into a ranked placement recommendation with a deployment-ready diff.

// 01 — install

shell
git clone https://github.com/akislenkova/spoticker.git
cd spoticker/mcp
pip install -e .

requires Python 3.11+. the spoticker-mcp command is added to your PATH after install.

.env (mcp/ directory or shell exports)
ANTHROPIC_API_KEY=sk-ant-...          # required for analyze_workload
SUPABASE_URL=https://xxxx.supabase.co  # required for get_spot_prices + analyze_workload
SUPABASE_SERVICE_KEY=eyJ...            # required for get_spot_prices + analyze_workload
AWS_ACCESS_KEY_ID=AKIA...             # required for get_spot_placement_score
AWS_SECRET_ACCESS_KEY=...             # required for get_spot_placement_score

ANTHROPIC_API_KEY is only needed for analyze_workload (stages 2 and 4 call Claude for spec inference and diff generation). Supabase keys are required for get_spot_prices and analyze_workload. AWS credentials are only needed for get_spot_placement_score — alternatively, configure ~/.aws/credentials and pass aws_profile at call time.

// 02 — configure your harness

Claude Code

~/.claude/settings.json
// ~/.claude/settings.json  (or project-level .claude/settings.json)
{
  "mcpServers": {
    "spoticker": {
      "command": "spoticker-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "SUPABASE_URL": "https://xxxx.supabase.co",
        "SUPABASE_SERVICE_KEY": "eyJ...service_role..."
      }
    }
  }
}

Use ~/.claude/settings.json for global access, or .claude/settings.json at your project root to scope it to one repo. Run /mcp in Claude Code to verify the server loaded.

Claude Desktop

claude_desktop_config.json
// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "spoticker": {
      "command": "spoticker-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "SUPABASE_URL": "https://xxxx.supabase.co",
        "SUPABASE_SERVICE_KEY": "eyJ...service_role..."
      }
    }
  }
}

Cursor / Windsurf

.cursor/mcp.json
// .cursor/mcp.json  (project root)
{
  "mcpServers": {
    "spoticker": {
      "command": "spoticker-mcp",
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "SUPABASE_URL": "https://xxxx.supabase.co",
        "SUPABASE_SERVICE_KEY": "eyJ...service_role..."
      }
    }
  }
}

Windsurf uses ~/.codeium/windsurf/mcp_config.json with the same schema.

// 03 — tool reference

get_spot_prices

Query live GPU spot prices from the Spoticker database. All parameters are optional — omit to return everything.

gpu_typestring?"H100" | "A100-80GB" | "A100-40GB" | "V100" | "A10G" | "L4" | "T4"
cloudstring?"aws" | "azure" | "gcp" — omit for all providers
min_gpusintminimum GPU count required (default 1)
limitintmax results, sorted cheapest-first (default 20)
Returns list of { cloud, region, sku, gpu_type, gpu_count, hourly_price_usd, ondemand_price_usd, eviction_rate, eviction_source, eviction_note }
example calls
// find cheapest H100 spots across all clouds
get_spot_prices(gpu_type="H100", limit=10)

// 4× A100 options on AWS only
get_spot_prices(gpu_type="A100-80GB", cloud="aws", min_gpus=4)

// everything available right now (up to 20 results)
get_spot_prices()

get_spot_placement_score

Query AWS Spot Placement Scores via the EC2 API. Returns a real-time 1–10 likelihood score per region indicating how likely AWS is to fulfill a spot request right now. More actionable than historical eviction buckets for placement decisions.

instance_typestringEC2 instance type, e.g. "p5.48xlarge", "p4d.24xlarge", "g5.xlarge"
target_capacityintnumber of instances requested — affects score (default 1)
regionslist?AWS region names to score, e.g. ["us-east-1", "us-west-2"]. Omit for all regions.
aws_profilestring?named profile from ~/.aws/credentials, e.g. "work". Omit to use default chain.
Returns list of { region, score, instance_type } sorted by score descending (10 = best availability). Needs ec2:DescribeSpotPlacementScores permission.
example calls
// live placement scores for H100 (p5.48xlarge) across all regions
get_spot_placement_score(instance_type="p5.48xlarge")

// target 4 instances, check specific regions
get_spot_placement_score(instance_type="p4d.24xlarge", target_capacity=4, regions=["us-east-1", "us-west-2"])

// use a named AWS profile
get_spot_placement_score(instance_type="g5.xlarge", aws_profile="work")

analyze_workload

5-stage pipeline: parse artifact → infer missing specs via Claude → rank live spot candidates → rewrite artifact → validate output. Returns a unified diff + migration commands ready to apply.

fileslist[{"path": "<name>", "content": "<text>"}] — Dockerfile, k8s YAML, Terraform .tf, Helm values
objectivestring"cost" | "cost_reliability" | "ha_multi_cloud" (default: cost_reliability)
intentstring?free-text guidance for ambiguous artifacts, e.g. "train a 7B model for 8h"

Returns PlanResult:

specextracted workload spec (GPU type, count, framework, env vars)
candidatestop 5 ranked placements with prices and eviction rates
chosenthe top recommendation
rewriteunified diff + migration_commands to update your artifact
validation_passedwhether the rewritten artifact passed structural checks
errorset if no candidates found or pipeline failed
example calls
// pass a Dockerfile and let the pipeline recommend placement
analyze_workload(
  files=[{"path": "Dockerfile", "content": "<your dockerfile>"}],
  objective="cost_reliability"
)

// with an explicit intent to guide inference
analyze_workload(
  files=[{"path": "train.yaml", "content": "<k8s manifest>"}],
  objective="cost",
  intent="train a 7B LLaMA model for ~8 hours, need at least 2× H100"
)

// 04 — example agent prompts

Copy any of these into your agent to verify the integration is working.

>_

What's the cheapest H100 spot available right now across all clouds?

>_

Get me 4× A100-80GB options under $12/hr, preferably with low eviction.

>_

Check AWS Spot Placement Scores for p5.48xlarge across all regions.

>_

Analyze my Dockerfile and recommend the best spot placement for a training job.

>_

Compare AWS vs Azure spot prices for a single A10G GPU.

>_

I need multi-cloud HA for my inference workload — analyze my k8s YAML.

// source

github.com/akislenkova/spoticker — MCP server source is in mcp/. Issues and PRs welcome.