# Balatro Agent [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/Arcadi4/balatro-agent  
**GitHub Stars:** 21  
**npm Downloads (last month):** 1354  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/balatro-mcp

## Description
MCP server connecting AI agents to play Balatro

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "balatro-agent": {
    "command": "npx",
    "args": ["-y","balatro-mcp"]
  }
}
```

## Documentation

## What the Balatro Agent MCP server does

The Balatro Agent MCP server lets an AI client control a running, modded copy of Balatro. Communication happens through MCP tool calls and resources rather than screenshots or visual input. The agent can inspect the current game state, consult reference material, and take actions that a human player could perform.

The project is intended for the 🎮 Gaming category and connects to the Steam edition of Balatro. It does not operate as a standalone game client; Balatro must be installed and running with the required mod components enabled.

## How it works

A Lua mod installed in Balatro exposes the game-side functionality. An MCP server launched with `npx -y balatro-mcp` connects an MCP-compatible client to that running game. The client sends text tool calls, while live game state and wiki content are provided as MCP resources.

This design allows an agent to make decisions from structured state instead of interpreting a video feed. It can begin or resume a run, inspect available cards and mechanics, then issue actions such as playing a hand or purchasing an item. Client support for MCP resources matters because current state and wiki pages are delivered through that part of the protocol.

## Setup and configuration

Install Balatro through Steam, then install Lovely Injector and Steamodded according to their platform instructions. Download the Balatro Agent mod from a release or Nexus Mods and place it in the appropriate Balatro `Mods` directory. The installed files should include `Balatro/Mods/balatro-agent/main.lua`.

The documented platform paths are:

- macOS: `~/Library/Application Support/Balatro/Mods/`
- Windows: `%AppData%\\Balatro\\Mods\\`
- Linux: `~/.local/share/love/Balatro/Mods/`
- Linux through Proton: the Balatro Steam compatibility-data path under `AppData/Roaming/Balatro/Mods/`

Node.js 20 or newer is required when launching through `npx`. Native archives from GitHub Releases can run without Node.js. Add the server to the MCP client configuration, for example with the command `npx` and arguments `-y balatro-mcp`, then start Balatro with the mod enabled before starting the client.

## Tools and capabilities

The Balatro Agent MCP server supports gameplay actions including:

- Starting, continuing, and restarting runs
- Choosing or skipping blinds
- Sorting, selecting, playing, and discarding cards
- Buying jokers, consumables, vouchers, and booster packs
- Rerolling the shop and cashing out
- Using and selling cards
- Reordering jokers to change trigger order
- Selecting decks, stakes, and challenges

It also provides a play handbook, reference data, and live lookups for cards, blinds, and game mechanics from the Balatro Wiki. These references are exposed alongside the live game state as MCP resources.

## Limitations and notes

Compatibility depends on the Balatro mod stack and the client’s MCP resource support. If a client cannot properly read MCP resources, the agent may not be able to access the current game state or wiki pages even if tool calls are available.

The README notes that Balatro v1.1 was upcoming and that releases after that version would not guarantee compatibility with the v1.0 game. Check the project’s current release information before updating the game. The server also requires Balatro to be running with Lovely Injector, Steamodded, and the Balatro Agent mod installed; it does not replace those components.

_Full upstream README: https://allmcps.com/mcp/balatro-mcp/readme_