STS2 MCP

An Experimental Research Project to Fully-Automate your Slay the Spire 2 Runs

A mod for Slay the Spire 2 that lets AI agents play the game. Exposes game state and actions via a localhost REST API, with an optional MCP server for Claude Desktop / Claude Code integration.

Singleplayer and multiplayer (co-op) supported. Tested against STS2 v0.99.1.

[!warning]
This mod allows external programs to read and control your game via a localhost API. Use at your own risk with runs you care less about.

[!caution]
Multiplayer support is in beta — expect bugs. Any multiplayer issues encountered with this mod installed are very likely caused by the mod, not the game. Please disable the mod and verify the issue persists before reporting bugs to the STS2 developers.

For Players

Install

Grab the latest release and follow the instructions:

Copy STS2_MCP.dll and STS2_MCP.json to <game_install>/mods/
Launch the game and enable mods in settings (a consent dialog appears on first launch)
The mod starts an HTTP server on localhost:15526 automatically

Connect to Claude

Requires Python 3.11+ and uv.

Clone or download the repository, then:

Claude Code — add to your project's .mcp.json:

{
  "mcpServers": {
    "sts2": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/STS2_MCP/mcp", "python", "server.py"]
    }
  }
}

Claude Desktop — add to claude_desktop_config.json with the same config as above.

The MCP server accepts --host and --port flags if you need non-default settings.

Full tool reference: mcp/README.md | Raw HTTP API: docs/raw_api.md

For Developers

Build & Install

Requires .NET 9 SDK.

PowerShell (recommended):

# Pass game path directly:
.\build.ps1 -GameDir "D:\SteamLibrary\steamapps\common\Slay the Spire 2"

# Or set it once and forget:
$env:STS2_GAME_DIR = "D:\SteamLibrary\steamapps\common\Slay the Spire 2"
.\build.ps1

The script builds STS2_MCP.dll into out/STS2_MCP/. Copy it along with the manifest JSON to <game_install>/mods/ to install:

out/STS2_MCP/STS2_MCP.dll           ->  <game_install>/mods/STS2_MCP.dll
mod_manifest.json                   ->  <game_install>/mods/STS2_MCP.json

Features

Singleplayer — full coverage of all game screens:

Combat (play cards, use potions, end turn, in-combat card selection), rewards (claim, pick/skip cards), map navigation (full DAG with lookahead), rest sites, shop, events & ancients, card selection overlays (transform, upgrade, remove), relic selection, treasure rooms, keyword glossary across all entities.

Multiplayer (beta) — all singleplayer features plus:

End-turn voting (submit/undo), map node voting, shared event voting, treasure relic bidding, all-players state summary, per-player ready/vote tracking. Endpoints are mutually guarded (singleplayer endpoint rejects multiplayer runs and vice versa).

License

MIT

FAQ

Why let the AI play the game for me?

I start building this mod with the hope that I can co-op with an AI player. Singleplayer is originally just built for validation.

You did not answer the question!

First of all, I play lots of games, including service games that has daily/weekly tasks. I really hoped that modern AI could save me from the grind, which, if you have tried one or more of the GUI agents, never really materialized. Let's face it: modern AI is still pretty bad at gaming because no one cares.

About my intention, as a researcher that loves playing games, the purpose of STS2MCP is to test AI models and agents in a rarely explored (we call it out-of-distribution) domain. Ultimately, this might turn into a benchmark for evaluating the reasoning and decision-making capabilities of different language models.

STS2 is just an example to show how good (or bad) current AI agents are at playing such games. I have no intention to replace human players with AI, and I would definitely rather play STS2 myself as a big fan of the game.

Is this a cheat mod?

It can be, but it doesn't have to be. The mod itself does not alter the gameplay. It is just an interface that allows external programs to interact with the game. What you do with that interface is up to you.

How many tokens do a run consume?

I evaluated on the Ironclad. Claude Sonnet 4.6 uses slightly more than 8M tokens (counting both input, output and tool responses) for a full run. GPT-5.4 averages 7.34M tokens. Depending on your prompt and model choice, it can be more or less.

Do you have a roadmap for future features?

The project is still too early to have a clear roadmap. My current focus is to make sure the core features are stable and well-documented. However, I am open to suggestions and contributions from the community.

Solidifying multiplayer features and fixing bugs is a priority
Add support for in-game communication in multiplayer runs when collaborating with an AI agent
Self-reflection and learning from past runs to improve future performance
Benchmarking different models and agents is also on my mind