Brotato Coach

A deterministic theorycrafter for Brotato, delivered as an MCP server you can chat with from Claude Code (and other MCP clients).

The design principle: a deterministic core holds the ground truth — weapon/item/character data, DPS formulas, stat mechanics — so the language model looks facts up and computes instead of recalling (and misremembering) them. Every tool returns a finished, verifiable answer or a structured error; there are no baked-in tier lists or opinions, only facts and math.

The dataset (data/brotato.json) is not committed — it is derived from copyrighted game files, so you build it yourself from a local Brotato install (see Building the dataset). A full build from Brotato 1.1.15.4 contains 202 weapons, 197 items, 50 characters, and 15 weapon-class sets.

Requirements

• Python 3.11+
• uv for environment/dependency management

Install dependencies:

uv sync

Quick start

Build the dataset (needs a local extraction — see Building the dataset), then start the server:

uv run python build_dataset.py                        # writes data/brotato.json
uv run python -m brotato_coach.server                 # starts the MCP server over stdio

The server refuses to start without data/brotato.json and tells you to build it first.

Run the tests (the dataset-dependent integration test is skipped when no dataset is built):

uv run pytest        # 89 tests (88 passed + 1 skipped without a built dataset)

Run

uvx spudcoach --data /path/to/brotato.json

The dataset is never distributed — build your own from your Brotato install: uv run python build_dataset.py (see docs/extraction-setup.md). Game version auto-detects from the decompiled recovered/singletons/progress_data.gd, and generated_at defaults to the current UTC time — pass --game-version/--generated-at explicitly to override either. SPUDCOACH_DATA works as an env-var alternative to --data.

Use as a Claude Code plugin

The MCP server is described by plugin/.mcp.json:

{
  "mcpServers": {
    "spudcoach": {
      "command": "uv",
      "args": ["run", "python", "-m", "brotato_coach.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

The server reads the (locally built) data/brotato.json relative to its working directory, so it must run with the repository root as its cwd (the manifest handles this via ${CLAUDE_PLUGIN_ROOT} when bundled as a plugin), and you must build the dataset first.

To register it directly in Claude Code without packaging, add the server pointed at your checkout, e.g.:

claude mcp add spudcoach -- uv run --directory /path/to/spud-coach python -m brotato_coach.server

Once connected, just ask in natural language — the model routes your question to the tools below:

• "Does Handcuffs fit my Ranger run? I'm at 7 ranged damage, 65 HP."
• "Minigun T4 vs Revolver T4 at 20 ranged damage — which hits harder?"
• "Is attack speed ever dead weight? Can I let knockback go negative on a gun build?"
• "What does the Ranger's ranged-damage bonus do to a raw stat of 6?"
• "Here's my run.json — how's this build doing?" (post-mortem a whole save at once)

Use with Claude Desktop

Claude Desktop can launch the server with uvx in two forms: fetch straight from this repo (auto-updates on restart, but needs git reachable — see the Windows note below), or point at a local checkout (nothing fetched at runtime; the most reliable form on Windows). Either way you supply your own locally built brotato.json — the dataset is never distributed.

1. Install uv on the machine running Claude Desktop (winget install astral-sh.uv on Windows, or the standalone installer).

2. Open the config file and add the spud-coach server:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Fetch-from-repo form:

   config.json

   Copy

   {
     "mcpServers": {
       "spud-coach": {
         "command": "uvx",
         "args": [
           "--from", "git+https://github.com/brendanlefebvre/spud-coach",
           "spudcoach",
           "--data", "C:\\Users\\<you>\\path\\to\\brotato.json"
         ]
       }
     }
   }
   

   Point --data at your built dataset (SPUDCOACH_DATA works as an env-var alternative). On macOS use a POSIX path like /Users/<you>/brotato.json.

3. Fully restart Claude Desktop (quit from the tray, not just close the window).

Windows: "Git executable not found" (or uvx not found)

The git+https://… form makes uv shell out to a git executable. Claude Desktop does not pass your shell — or even your System PATH — to the MCP subprocess; it spawns servers with its own trimmed environment. (The PATH it prints in the logs is its command-resolution list, not what the child process receives.) So a git that runs fine in PowerShell, installed in a System-PATH directory, can still come back "not found" here — and a bare "command": "uvx" can fail to resolve for the same reason. Two fixes:

• Point at a local checkout — no runtime git (recommended). Clone once in a terminal where git works, then use --from <folder> instead of --from git+…:

  powershell

  Copy

  git clone https://github.com/brendanlefebvre/spud-coach C:\Users\<you>\src\spud-coach
  

  config.json

  Copy

  {
    "mcpServers": {
      "spud-coach": {
        "command": "uvx",
        "args": ["--from", "C:\\Users\\<you>\\src\\spud-coach", "spudcoach",
                 "--data", "C:\\Users\\<you>\\path\\to\\brotato.json"]
      }
    }
  }
  

  Update later with git pull in that folder, then restart Desktop.

• Or force the tools onto the server's PATH. Keep the git+https form and add an env block that hands the child an explicit PATH — git, plus uv's bin and the winget-links dir:

  json

  Copy

  "env": {
    "PATH": "C:\\Program Files\\Git\\cmd;C:\\Users\\<you>\\.local\\bin;C:\\Users\\<you>\\AppData\\Local\\Microsoft\\WinGet\\Links;C:\\Windows\\System32"
  }
  

  If uvx itself still isn't found, also set "command" to its absolute path (Get-Command uvx to locate it, e.g. C:\Users\<you>\AppData\Local\Microsoft\WinGet\Links\uvx.exe).

Available tools

All tools return a JSON object. Lookups that miss return {"error": "not_found", "did_you_mean": [...]}.

22 tools. Arguments marked ? are optional.

Start here

Data lookups

DPS & comparison

Build evaluation

Bestiary