Let an AI agent play Balatro for you. Balatro Agent connects any MCP-compatible AI client to a running game: the agent reads the live game state, picks blinds, plays and discards hands, shops for jokers, and manages your run. No screen capture or model vision required, everything works over text.

Requirements

• Balatro on Steam
• Lovely Injector
• Steamodded (SMODS)
• Bun 1.3.14 or later to run the MCP server (will publish a npm package later so this would not be needed)

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

Copy the mod folder from this repository into Balatro's Mods directory:

[!TIP]
On macOS you can run make install-mods from the repository root instead of copying by hand.

The result should look like .../Balatro/Mods/balatro_mcp/main.lua.

3. Install the server

cd mcp
bun install

4. Connect your MCP client

Add the server to your MCP client configuration (Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "balatro": {
      "command": "bun",
      "args": ["/absolute/path/to/balatro-mcp/mcp/src/index.ts"]
    }
  }
}

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.