Balatro Agent

English | 简体中文

Let an AI agent play Balatro. Balatro Agent connects any MCP-compatible AI client to a running game. The agent may read the live game state, pick blinds, play and discard hands, purchase jokers, and anything a human player is capable of. No screen capture or model vision required, everything works over text-based tool calls.

balatro-agent.mp4

Requirements

• Balatro on Steam
• Lovely Injector
• Steamodded (SMODS)
• Node.js 20 or later for npx (it launches a native MCP binary; Bun, cloning, and building are not required). Native archives from GitHub Releases also run without Node.

Install

1. Install Lovely and SMODS

Follow the SMODS installation guide for your platform. This step is the same for every Balatro mod.

2. Install the Balatro Agent mod

Download and unpack the mod into Balatro's Mods directory:

• Nexus Mods: manual download, or use "Mod Manager Download" together with the community Vortex extension, which also installs Lovely and Steamodded for you.
• GitHub Releases: grab balatro-agent-vX.Y.Z.zip from the latest release.

Platform	Mods directory
macOS	~/Library/Application Support/Balatro/Mods/
Windows	%AppData%\Balatro\Mods\
Linux (native)	~/.local/share/love/Balatro/Mods/
Linux (Proton)	~/.steam/steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/

Tip

On macOS you can clone and run make install-mods from the repository root instead of copying by hand.

The result should look like .../Balatro/Mods/balatro-agent/main.lua.

3. Connect your Agent

Add the server to your MCP client configuration (Claude Code, Cursor, etc.), check the corresponding tutorials/docs. The config file might look like:

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

The command in one line:

npx -y balatro-mcp

Start Playing

1. Start Balatro with the mod enabled.

2. Start your MCP client.

3. Ask the agent to play, for example:

   Start a new run with the Red Deck and play through Ante 1.

Features

• Provides basic tools to select or skip blinds, play and discard hands, sort and select cards
• Interact with the shop to buy jokers, consumables, vouchers and boosters, reroll, cash out
• Use and sell cards, reorder jokers for optimal trigger order
• Start, continue, and restart runs with any deck, stake, or challenges
• Provides a built-in Balatro rule doc, plus live lookup of every card, blind, and mechanic from the Balatro Wiki

Important

Wiki was exposed as MCP resoruces. If your agent client does not support resources properly, agents might not have access to wiki pages.