mcp server

balatro-agent

Let AI agents play Balatro

Arcadi4/balatro-agentcommunitylistedunreviewednot running here yet

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

~/Library/Application Support/Claude/claude_desktop_config.json

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

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 14, 2026

Balatro Agent

English | 简体中文

Let an AI agent play Balatro. Balatro Agent connects any MCP-compatible AI client to a running game. The agent can read live state, pick blinds, play and discard hands, buy jokers, and perform any action available to a human player. It needs no screen capture or vision model; everything works through text tool calls.

https://github.com/user-attachments/assets/bcb40bd1-a9f8-491c-9a98-6f1a11c90fab

[!IMPORTANT] Balatro v1.1 is coming. I will try to provide support asap when its released. Any release after that will not guarantee compatibility with the v1.0 game.

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 whole command on one line:

npx -y balatro-mcp

Start Playing

Start Balatro with the mod enabled.
Start your MCP client.
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 play handbook and reference data, plus live lookup of cards, blinds, and mechanics from the Balatro Wiki

[!IMPORTANT] Live game state and the wiki are exposed as MCP resources. If your agent client does not support resources properly, the agent may be unable to read the current game state or wiki pages.