AgentStack
Browse Sign in
Browse Why AgentStack Sell Docs
Sign in
MCP verified MIT Self-run

Balatro MCP

mcp-gdnaiteab-balatro-mcp · by Gdnaiteab

Balatro MCP server and Steamodded mod exposing game state and actions over localhost HTTP for AI clients.

↗ Repository
— No reviews yet
0 installs
5 views
0.0% view→install

Install

$ agentstack add mcp-gdnaiteab-balatro-mcp

✓ scanned · ✓ verified, works with Claude Code, Cursor, and more.

Security review

✓ Passed

No issues found. Passed automated security review. · v0.1.0 How review works →

  • ✓ Prompt-injection patterns
  • ✓ Secret / credential exfiltration
  • ✓ Dangerous shell & filesystem operations
  • ✓ Untrusted network calls
  • ✓ Known-malicious package signatures

What it can access

  • ✓ Network access No
  • ✓ Filesystem access No
  • ✓ Shell / process execution No
  • ✓ Environment & secrets No
  • ✓ Dynamic code execution No

From automated source analysis of v0.1.0. “Used” means the capability is present in the source — more access means more to trust, not that it’s unsafe.

View the full security report →

Verified badge

Passed review? Show it. Paste this badge into your README, it links to the public security report.

AgentStack Verified badge Links to your public security report.
[![AgentStack Verified](https://agentstack.voostack.com/badges/verified.svg)](https://agentstack.voostack.com/security/report/mcp-gdnaiteab-balatro-mcp)

Reliability & compatibility

✓ Security review passed
0 installs to date
— no reviews yet
● 2mo ago

Declared compatibility

Claude CodeClaude DesktopCursorWindsurf

Compatibility is declared by the source manifest. End-to-end runtime verification is coming, see below.

Preview Execution monitoring

We're building live execution health for every listing: tool-call success rate, median latency, uptime, and last-checked timestamps, measured, not self-reported. It isn't live yet, so we don't show numbers we can't stand behind.

How agent discovery & health will work →
Are you the author of Balatro MCP? Claim this listing to set pricing, connect Stripe payouts, and keep 70% of every sale.
Sign up to claim

About

Balatro MCP

中文 README: [README.zh-CN.md](./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](./LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

Install and usage instructions live in the source repository linked above.

Reviews

No reviews yet, be the first.

Write a review

Versions

  • v0.1.0 Imported from the upstream source.

More in Integrations