Skip to content
Back to search

STS2MCP

Full agentic runs for Slay the Spire 2. A mod that exposes in-game state, and the MCP server for the mod.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gennadiyev--sts2mcp/badge.svg)](/listings/gennadiyev--sts2mcp)

HTML

<a href="/listings/gennadiyev--sts2mcp"><img src="/api/listings/gennadiyev--sts2mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Grab the [latest release](https://github.com/Gennadiyev/STS2MCP/releases/latest) and follow the instructions:

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

> [!note] > The release DLL is a platform-agnostic .NET assembly — the same `STS2_MCP.dll` and `STS2_MCP.json` work on Windows, Linux, and macOS. No separate builds are needed.

macOS install

On macOS, the mods directory lives inside the app bundle. The default Steam install path is:

~/Library/Application Support/Steam/steamapps/common/Slay the Spire 2/
    SlayTheSpire2.app/Contents/MacOS/mods/

To install, right-click `SlayTheSpire2.app` → **Show Package Contents**, navigate to `Contents/MacOS/`, and create a `mods` folder. Or from the terminal:

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/"

Launch the game and open **Settings → Mods**. The mod should appear in the list. A consent dialog appears on first launch — accept it to enable mod loading. Once enabled, verify the HTTP server is running:

curl -s http://localhost:15526/

A successful response looks like:

{"message": "Hello from STS2 MCP v0.3.4", "status": "ok"}

If you get "Connection refused", the mod is not loaded — check that mods are enabled in the game's settings.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 214 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="docs/teaser.png" alt="STS2 MCP" width="90%" />
  3. </p>
  4. <p align="center"><em>An Experimental Research Project to Fully-Automate your Slay the Spire 2 Runs</em></p>
  5. A mod for [**Slay the Spire 2**](https://store.steampowered.com/app/2868840/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.
  6. Singleplayer and multiplayer (co-op) supported, plus full menu and lobby control: profile switching, character select (SP and MP host/client) with optional seed, multiplayer host / Steam-friend join / FastMP localhost join, multiplayer load lobby for resuming saved co-op runs, game-over dismissal, FTUE/tutorial popup handling, and Timeline visibility. Tested against STS2 `v0.103.2`.
  7. > [!warning]
  8. > 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.
  9. > [!caution]
  10. > 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.
  11. ## For Players
  12. ### 1. Install the Mod
  13. Grab the [latest release](https://github.com/Gennadiyev/STS2MCP/releases/latest) and follow the instructions:
  14. 1. Copy `STS2_MCP.dll` and `STS2_MCP.json` to `<game_install>/mods/`
  15. 2. Launch the game and enable mods in settings (a consent dialog appears on first launch)
  16. 3. The mod starts an HTTP server on `localhost:15526` automatically
  17. > [!note]
  18. > The release DLL is a platform-agnostic .NET assembly — the same `STS2_MCP.dll` and `STS2_MCP.json` work on Windows, Linux, and macOS. No separate builds are needed.
  19. #### macOS install
  20. On macOS, the mods directory lives inside the app bundle. The default Steam install path is:
  21. ```
  22. ~/Library/Application Support/Steam/steamapps/common/Slay the Spire 2/
  23. SlayTheSpire2.app/Contents/MacOS/mods/
  24. ```
  25. To install, right-click `SlayTheSpire2.app` → **Show Package Contents**, navigate to `Contents/MacOS/`, and create a `mods` folder. Or from the terminal:
  26. ```bash
  27. GAME_DIR="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"
  28. MODS_DIR="$GAME_DIR/SlayTheSpire2.app/Contents/MacOS/mods"
  29. mkdir -p "$MODS_DIR"
  30. cp STS2_MCP.dll "$MODS_DIR/"
  31. cp STS2_MCP.json "$MODS_DIR/"
  32. ```
  33. Launch the game and open **Settings → Mods**. The mod should appear in the list. A consent dialog appears on first launch — accept it to enable mod loading. Once enabled, verify the HTTP server is running:
  34. ```bash
  35. curl -s http://localhost:15526/
  36. ```
  37. A successful response looks like:
  38. ```json
  39. {"message": "Hello from STS2 MCP v0.3.4", "status": "ok"}
  40. ```
  41. If you get "Connection refused", the mod is not loaded — check that mods are enabled in the game's settings.
  42. ### 2. Give Your AI Instructions to Interact with the Game
  43. **Clone or download the repository**, then:
  44. | I prefer a skill | I prefer an MCP Server |
  45. |---|---|
  46. | Tell AI to reference docs/raw-*.md. Sit back, and watch it play. | Requires [Python 3.11+](https://www.python.org/) and [uv](https://docs.astral.sh/uv/). Follow the instructions below ⬇️ |
  47. #### MCP server setup
  48. Install [uv](https://docs.astral.sh/uv/) if you don't have it (macOS: `brew install uv`). Then run the server once to install dependencies:
  49. ```bash
  50. uv run --directory /path/to/STS2_MCP/mcp python server.py --help
  51. ```
  52. `uv` reads `mcp/pyproject.toml`, creates an isolated virtual environment, and installs the pinned dependencies from `mcp/uv.lock`. Subsequent runs reuse the environment instantly.
  53. Add the server to your AI client's MCP config:
  54. ```json
  55. {
  56. "mcpServers": {
  57. "sts2": {
  58. "command": "uv",
  59. "args": ["run", "--directory", "/path/to/STS2_MCP/mcp", "python", "server.py"]
  60. }
  61. }
  62. }
  63. ```
  64. **Claude Code**: add to your project's `.mcp.json`.
  65. **Claude Desktop**: add to `claude_desktop_config.json` with the same config as above.
  66. *Other agents should have similar config options for custom MCP servers.*
  67. > [!tip]
  68. > On macOS, use the absolute path to `uv` (e.g. `/opt/homebrew/bin/uv`) in the `command` field. GUI-launched apps may not inherit your shell's `PATH`, which would prevent the server from starting.
  69. Restart your Claude session after adding the config. To verify the MCP server is working, ask Claude to call `get_game_state` — with the game running, it should return the current game state.
  70. The MCP server accepts `--host` and `--port` options if you need non-default settings.
  71. Flag `--no-trust-env` can be used to disable `requests` from picking up proxy settings from the environment, which can cause connection issues if you are running the server in a container.
  72. ### Profile and Compendium Data
  73. The HTTP API exposes profile-level progress separately from live run state:
  74. - `GET /api/v1/profile` returns the active profile's persistent progress summary, including discoveries, achievements, epochs, character totals, and global run totals.
  75. - `GET /api/v1/compendium` groups that progress into the same high-level sections as the in-game Compendium: Card Library, Relic Collection, Potion Lab, Bestiary, Character Stats, and Run History.
  76. - `GET /api/v1/wiki?query=...` searches discovered card and relic wiki entries for the active profile with fuzzy matching. Results are limited to 10 by default and can be overridden with `limit`; card results include base and upgraded variants when available.
  77. - `GET /api/v1/profiles` lists the three profile slots and the active profile.
  78. - `POST /api/v1/profiles` switches or deletes profile slots through the game UI.
  79. The MCP server exposes the same profile data through `get_profile()`, `get_compendium()`, `search_wiki(query, item_type, limit)`, `list_profiles()`, `switch_profile(profile_id)`, and `delete_profile(profile_id)`.
  80. `get_compendium()` is intended for agents that need durable context outside the current room or current run. It works from the main menu, includes a `current_run` block while a run is active, and summarizes saved `saves/history/*.run` files for the active profile. Run history is capped to the 20 most recent files in the response so long-lived profiles do not create unbounded tool output.
  81. `search_wiki()` is the selective lookup path for durable card and relic text. It never returns the full game catalog: the mod first filters to the active profile's discovered card and relic IDs, then returns only the best fuzzy matches. Use `item_type="card"` or `item_type="relic"` when the query is known, and raise `limit` only when the default 10 results are not enough.
  82. ## For Developers
  83. ### Build & Install
  84. Requires [.NET 9 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) and the base game.
  85. **PowerShell** (recommended):
  86. ```powershell
  87. # Pass game path directly:
  88. .\build.ps1 -GameDir "D:\SteamLibrary\steamapps\common\Slay the Spire 2"
  89. # Or set it once and forget:
  90. $env:STS2_GAME_DIR = "D:\SteamLibrary\steamapps\common\Slay the Spire 2"
  91. .\build.ps1
  92. ```
  93. The script builds `STS2_MCP.dll` into `out/STS2_MCP/`. Copy it along with the manifest JSON to `<game_install>/mods/` to install:
  94. ```
  95. out/STS2_MCP/STS2_MCP.dll -> <game_install>/mods/STS2_MCP.dll
  96. mod_manifest.json -> <game_install>/mods/STS2_MCP.json
  97. ```
  98. ### Build instructions for macOS
  99. Install dotnet to compile the mod:
  100. ```bash
  101. brew install dotnet@9
  102. export DOTNET_ROOT="/opt/homebrew/opt/dotnet@9/libexec"
  103. export PATH="$DOTNET_ROOT:$PATH"
  104. ```
  105. Homebrew installs `dotnet@9` as keg-only, so the exports above are required for the current session. Add them to `~/.zshrc` to persist across sessions.
  106. Build with `dotnet` directly (the PowerShell script is Windows-only):
  107. ```bash
  108. dotnet build STS2_MCP.csproj -c Release -o out/STS2_MCP \
  109. -p:STS2GameDir="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"
  110. ```
  111. On macOS the game ships as an app bundle. The `.csproj` detects macOS and resolves the data directory to `SlayTheSpire2.app/Contents/Resources/data_sts2_macos_arm64` automatically.
  112. The mods directory on macOS lives inside the app bundle at `SlayTheSpire2.app/Contents/MacOS/mods/`. Finder hides bundle contents by default — to browse it in the GUI, right-click `SlayTheSpire2.app` → **Show Package Contents**. Or copy from the terminal:
  113. ```bash
  114. GAME_DIR="$HOME/Library/Application Support/Steam/steamapps/common/Slay the Spire 2"
  115. MODS_DIR="$GAME_DIR/SlayTheSpire2.app/Contents/MacOS/mods"
  116. mkdir -p "$MODS_DIR"
  117. cp out/STS2_MCP/STS2_MCP.dll "$MODS_DIR/"
  118. cp mod_manifest.json "$MODS_DIR/STS2_MCP.json"
  119. ```
  120. > [!NOTE]
  121. > `mod_manifest.json` is renamed to `STS2_MCP.json` on copy — the game's mod loader expects the manifest filename to match the mod ID.
  122. ## License
  123. MIT
  124. ## FAQ
  125. ### Why let the AI play the game for me?
  126. I start building this mod with the hope that I can co-op with an AI player. Singleplayer is originally just built for validation.
  127. ### You did not answer the question!
  128. 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.
  129. 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.
  130. 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.
  131. ### Is this a cheat mod?
  132. 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.
  133. ### How many tokens do a run consume?
  134. 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.
  135. ### Do you have a roadmap for future features?
  136. 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.
  137. - Solidifying multiplayer features and fixing bugs is a priority
  138. - Add support for in-game communication in multiplayer runs when collaborating with an AI agent
  139. - Self-reflection and learning from past runs to improve future performance
  140. - Benchmarking different models and agents is also on my mind

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.