# Balatro MCP

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-gdnaiteab-balatro-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Gdnaiteab](https://agentstack.voostack.com/s/gdnaiteab)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Gdnaiteab](https://github.com/Gdnaiteab)
- **Source:** https://github.com/Gdnaiteab/Balatro-MCP

## Install

```sh
agentstack add mcp-gdnaiteab-balatro-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## 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:

```powershell
D:\SteamLibrary\steamapps\common\Balatro
```

## Install

Install Lovely and Steamodded first. Then run:

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

## Start MCP

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

For network MCP:

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

## Action Examples

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

```json
{"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:

```json
{"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:

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

Local structure validation:

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

In-game smoke test:

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

## Acknowledgements

Balatro MCP is directly inspired by [CharTyr/STS2-Agent](https://github.com/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](https://github.com/Steamodded/smods) and [Lovely Injector](https://github.com/ethangreen-dev/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.

- **Author:** [Gdnaiteab](https://github.com/Gdnaiteab)
- **Source:** [Gdnaiteab/Balatro-MCP](https://github.com/Gdnaiteab/Balatro-MCP)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gdnaiteab-balatro-mcp
- Seller: https://agentstack.voostack.com/s/gdnaiteab
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.