Balatro MCP

中文 README: README.zh-CN.md

Balatro MCP is a Steamodded Balatro mod plus MCP server inspired by the architecture of STS2-Agent.

The in-game mod exposes Balatro state and actions through a local HTTP API on http://127.0.0.1:8080. The Python package in mcp_server/ wraps that API as MCP tools for AI clients.

Current Tool Surface

• GET /health
• GET /state
• GET /actions/available
• POST /action

MCP tools:

• health_check
• get_game_state
• get_raw_game_state
• get_available_actions
• list_legal_actions
• act
• wait_until_actionable
• continue_run
• choose_option
• choose_blind
• skip_choice
• select_card
• deselect_card
• play_hand
• discard_selected
• end_turn
• buy_item
• reroll_shop
• sell_joker
• use_consumable
• get_action_history
• get_run_summary

Local Balatro Path

The validation scripts default to:

D:\SteamLibrary\steamapps\common\Balatro

Install

Install Lovely and Steamodded first. Then run:

powershell -ExecutionPolicy Bypass -File scripts\install-local.ps1 -BalatroPath "D:\SteamLibrary\steamapps\common\Balatro"

Start MCP

powershell -ExecutionPolicy Bypass -File scripts\start-mcp-stdio.ps1

For network MCP:

powershell -ExecutionPolicy Bypass -File scripts\start-mcp-network.ps1

Action Examples

The generic MCP act tool accepts the action name plus optional arguments:

{"action": "start_run", "stake": 1}
{"action": "select_blind"}
{"action": "play_hand", "card_indices": [1, 2, 3, 4, 5]}
{"action": "discard", "card_indices": [6, 7]}
{"action": "buy", "area": "shop_jokers", "index": 1}
{"action": "use", "area": "consumeables", "index": 1, "card_indices": [1]}

For MCP clients that prefer task-shaped tools, the explicit tools wrap the same action layer:

{"tool": "continue_run", "stake": 1}
{"tool": "choose_blind", "option_id": "small"}
{"tool": "select_card", "index": 2}
{"tool": "play_hand", "card_indices": [1, 2, 3, 4, 5]}
{"tool": "buy_item", "area": "shop_jokers", "index": 1}
{"tool": "use_consumable", "index": 1, "card_indices": [1]}

Card, joker, shop, and consumable indexes are 1-based and come from get_game_state.

Validate

Static and MCP tests:

pytest tests/test_lua_static.py -q
cd mcp_server
uv run pytest -q

Local structure validation:

powershell -ExecutionPolicy Bypass -File scripts\validate-local.ps1 -SkipGameLaunch

In-game smoke test:

powershell -ExecutionPolicy Bypass -File scripts\validate-local.ps1 -LaunchGame

Acknowledgements

Balatro MCP is directly inspired by CharTyr/STS2-Agent. Thanks to CharTyr and the STS2-Agent project for demonstrating the practical mod-plus-MCP architecture this project adapts for Balatro.

This project also depends on the Balatro modding ecosystem built by Steamodded/smods and Lovely Injector. Thanks to those projects for making Lua-side Balatro mod loading and extension possible.

License

This project is licensed under the MIT License. See LICENSE.