Tools

STS2 MCP — AI Auto-Play Setup Guide

Install the STS2 MCP mod and connect Claude or any MCP agent to play Slay the Spire 2 hands-free.

Mod v0.3.4 · Tested on STS2 v0.103.2 · MIT License · Windows / macOS / Linux

What is STS2 MCP?

STS2 MCP is a community mod that exposes the game state and controls of Slay the Spire 2 over a localhost REST API, plus an optional MCP server. Point an AI agent at it and the model can read the board and play full runs on its own — an experimental project for fully automating your STS2 runs.

  • Full automation in both singleplayer and co-op, including menu, lobby and character selection
  • Real-time game state over HTTP on localhost:15526
  • Profile progress, compendium and fuzzy wiki search for discovered cards and relics
  • Works with Claude Code, Claude Desktop, or any custom MCP client

Requirements

Slay the Spire 2 base game (tested on v0.103.2)

Python 3.11+ and the uv package manager (only needed for the MCP server)

Claude Code, Claude Desktop, or another MCP-capable client

Step 1 — Install the Mod

The mod is a single DLL plus a manifest. Drop both into the game's mods folder and the HTTP server starts on its own.

  1. 1

    Download the latest release from the GitHub repository.

  2. 2

    Copy STS2_MCP.dll and STS2_MCP.json into [game_install]/mods/.Download

  3. 3

    Launch the game and enable mods in settings.

  4. 4

    The HTTP server starts automatically on localhost:15526.

macOS install path

On macOS the mods folder lives inside the app bundle. Run these commands to create it and copy the files in.

GAME_DIR="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"
MODS_DIR="$GAME_DIR/SlayTheSpire2.app/Contents/MacOS/mods"
mkdir -p "$MODS_DIR"
cp STS2_MCP.dll "$MODS_DIR/"
cp STS2_MCP.json "$MODS_DIR/"

Verify the install

With the game running, hit the root endpoint. A healthy install returns a version greeting.

curl -s http://localhost:15526/
{"message": "Hello from STS2 MCP v0.3.4", "status": "ok"}

Step 2 — Connect Your AI

The optional MCP server lets Claude talk to the mod through tool calls. It needs Python 3.11+ and uv.

Add this block to your Claude Code .mcp.json or Claude Desktop claude_desktop_config.json, pointing the directory at your local checkout.

{
  "mcpServers": {
    "sts2": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/STS2MCP/mcp", "python", "server.py"]
    }
  }
}
On macOS, use the absolute path to uv (e.g. /opt/homebrew/bin/uv) in the command field, otherwise Claude may not find it.

Optional flags

  • --host and --port to run on a non-default address.
  • --no-trust-env to ignore proxy environment variables.
Restart Claude after editing the config, then ask it to run get_game_state to confirm the connection.

API & MCP Tools Reference

If you are building your own agent, these are the surfaces the mod exposes. REST endpoints are reachable directly; the MCP server wraps them as tools.

REST endpoints

GET /api/v1/profilePersistent progress summary for the active profile.
GET /api/v1/compendiumHigh-level progress: card library, relics, potions, bestiary, character stats and run history.
GET /api/v1/wiki?query=...Fuzzy search across discovered cards and relics (10 results by default, override with limit).
GET /api/v1/profilesList the three profile slots and the active one.
POST /api/v1/profilesSwitch to or delete a profile slot.

MCP server tools

get_game_state()Current game state.
get_profile()Active profile data.
get_compendium()Durable context from the main menu or an active run.
search_wiki(query, item_type, limit)Selective card or relic lookup.
list_profiles()List profile slots.
switch_profile(profile_id)Switch the active profile.
delete_profile(profile_id)Delete a profile slot.

Token Cost

Running a full auto-play is token-heavy: roughly 8M tokens for a complete Ironclad run with Claude Sonnet 4.6 (input, output and tool responses combined), and about 7.34M with GPT-5.4. Plan API budget accordingly before letting an agent grind ascensions.

STS2 MCP is an open-source project by Gennadiyev, released under the MIT license. For releases, source and issues, see the repository.

View on GitHub