tmodloader-mcp

Drive a running tModLoader instance from an agent — launch it, ask it questions, photograph it, and read its state back as structured data.

How it works · Quick start · Configuration · Known limits

Game engines have grown MCP servers — Unity, Unreal, Godot and Defold all have one, so an assistant can see a real scene instead of guessing from a prompt. tModLoader has not had one. This is that.

_{The tool staged its own screenshot — time:noon, teleport:spawn, spawn:1,25, shot:full — read from the game's back buffer, so a window in front of the game cannot be in the picture (How it works starts there). Trimmed of the unexplored dark below the terrain; otherwise exactly as returned.}

Status: alpha — it has only ever run on one install; see Known limits before adopting it. Nothing defaults to anybody's install, the mod-side half is a folder you vendor (responder/), and CI compiles it with nothing of any mod's on the compile line.

Quick start

uv tool install tmodloader-mcp    # or: pip install tmodloader-mcp

# the two paths with no default — every plausible default names somebody's install
export TMODLOADER_SAVE_DIR="/mnt/c/Users/<you>/Documents/My Games/Terraria/tModLoader"
export TMODLOADER_MOD_SOURCE="$TMODLOADER_SAVE_DIR/ModSources/<YourMod>"

Then:

1. Vendor the responder — copy responder/ into your mod's source tree and subclass DevResponder. It is a folder of C#, not a PyPI dependency, because it compiles inside your mod.
2. Point your MCP client at the server — the block in Using it from Claude Code.
3. Ask the game something — launch, then diag. Or open with the start_a_session prompt, which lists the worlds and characters that actually exist here.

This needs WSL2 driving a Windows tModLoader — Requirements says why before anything else does.

How it works

The game is asked by writing a file it polls, not by sending it input:

┌─────────────────────────────────────────────────────┐
│  an agent — Claude Code, or anything speaking MCP   │
└──────────────────────┬──────────────────────────────┘
                       │  tools · prompts · capture:// resources
┌──────────────────────▼──────────────────────────────┐
│  tmodloader-mcp — this package (Python, WSL2)       │
└──────────────────────┬──────────────────────────────┘
                       │  writes  <mod>-capture.trigger
                       │  reads   <mod>-diag-<token>.txt,
                       │          <mod>-shot-<token>.png, ...
┌──────────────────────▼──────────────────────────────┐
│  the tModLoader save directory                      │
│  plain files on disk — no socket, no keystrokes     │
└──────────────────────▲──────────────────────────────┘
                       │  polls every few frames, writes
                       │  each answer next to its trigger
┌──────────────────────┴──────────────────────────────┐
│  DevResponder — C# you vendor into YOUR mod,        │
│  inside tModLoader, a real game, on Windows         │
└─────────────────────────────────────────────────────┘

No synthetic keystrokes, no window focus, and nothing that can be fooled by another window sitting on top of the game. That last point is the reason for the design: OS-level screen capture was tried first and returned a picture of Discord — a window in front of the game — while passing every check available. Reading the game's own back buffer cannot contain another window by construction, not by luck.

Captures name a region and have no default. The frame holds only the game, but that still includes a character name, a world name and any chat on screen, so a request says which corner it wants.

The mod side of that protocol — every filename, what each one contains, and which failures it has to be able to express — is written down in docs/MOD_CONTRACT.md, and implemented in responder/. You can read the contract or vendor the folder; the folder is the same document with a compiler checking it.

Since 0.6.0 replies are tagged: a request may carry a short id the responder echoes back first, so a late answer can never be mistaken for the next request's. Older vendored copies keep working — the tag is only sent to a responder that advertises taking it.

What the mod side answers

These are verbs, driven through the trigger tool, not separate MCP tools.

The reads come with the base class — every consumer serves them, and vendoring an upgrade can never hand your mod a power it did not have before:

The writes are opt-ins, each one line you write in RegisterCommands:

One line each is deliberately the whole mechanism: not a setting, not a marker file, not an environment variable, because each of those can be switched on somewhere other than the source somebody will read when they ask why an NPC appeared in their world. responder/README.md has the detail, including why DevCommandBridge is the answer to "what about an escape hatch" and why there is no reflect_invoke here.

The answers, verbatim

Every line below is real — the same server and client the live checks drive, quoted rather than paraphrased:

spawn:1,20        OK: spawned 20 of 20 id=1 at tile 2101,252

time:dusk         sent to a CLIENT:
                  REFUSED: "time" changes something the SERVER owns, and a
                  client that changed it would be corrected by the next world
                  packet - the change would appear to work and then undo
                  itself. Send this to the server: time@<server-address>.

give:8,5          sent to the SERVER:
                  REFUSED: "give" needs a local player, and a dedicated
                  server has none - it runs the world without standing in
                  it. Ask a client, by name.

spawn:0,1         REFUSED: 0 is not a NPC id - it is how Terraria spells
                  "nothing", so this would have succeeded and done nothing

spawn:banana,5    REFUSED: "banana" is not a positive whole NPC id

time:teatime      REFUSED: "teatime" is not one of dawn, noon, dusk, midnight

tiles:0,0,1000,1000
                  REFUSED: 1000 by 1000 is 1000000 tiles, past the limit of
                  16384 one query may scan

The refusals are the point. Each one says what was wrong, what would have been right, and — when the verb belongs to the other side of the wire — where to send it instead, because the reader is an agent and an agent retries exactly as well as the refusal explains.

The tool surface

Most of what this does could be a CLI, and where that is true it should stay one — a stateless local binary does not need a protocol in front of it. What earns the surface here is that a running game is not stateless:

A session

Asking the game

Pictures

Logs

Building, the API, and the saves

Those one-liners are where the hand-written version actually went wrong: a pkill pattern that matched its own command line, a readiness check that passed on a killed process's leftover heartbeat, and — for one stretch — a shot row promising a PNG check that did not exist: the file was waited for and renamed, never opened. It exists now, and reads the end that decides — a truncated PNG has a perfectly valid signature, so the trailer is what is checked. The gap was recorded here rather than quietly corrected, because a README is read by people deciding what they no longer have to check.

Two prompts ship with it: diagnose_silence walks the four reasons the mod might not answer, with this install's heartbeat, mod list and logs already read; start_a_session lists the worlds and characters that actually exist here — the two preconditions launch states and cannot check. Both render the failure into the text when the configuration is unusable, because a diagnostic that refuses to render has failed at the one moment it was for.

Captures are also addressable as capture://{name} resources. Both surfaces share one reader that takes a name, never a path, and serves only capture-shaped files inside the save directory — a reader that opened whatever it was handed would be the leak this project exists to prevent.

What it cannot do

There is no headless singleplayer. Terraria has no entry point for it — -join -player -skipselect lands at the main menu, measured rather than assumed. launch("singleplayer") refuses and says so instead of launching something else and letting you believe otherwise. Singleplayer testing needs a human to load a world; the other tools then drive it normally.

That matters more than it sounds: a bug that only appeared in singleplayer shipped once precisely because every harness ran server-plus-client.

There is no bare dedicated server either. An empty server runs no update hooks, so the mod never polls and never answers — measured on one process, changing only whether a client was attached: silent for 90s alone, answering within 30s of a client joining. launch("server") refuses for the same reason singleplayer does — what it promises is a game that can answer, and a server on its own never becomes one. Start one outside this tool if you want a server to join yourself.

Requirements

WSL2 on Windows, driving a Windows tModLoader. This is the one requirement worth reading before the others, because it is not a preference — sessions are listed and killed through Windows' own tasklist.exe and taskkill.exe, and build_mod hands tModLoader a Windows path because it builds inside a Windows process. A native Linux or macOS tModLoader cannot be driven by this as it stands. The configuration check every tool runs first says so by name rather than failing later on a missing file in System32; if you are on WSL and those tools live somewhere unusual, set TMODLOADER_TASKLIST, TMODLOADER_TASKKILL and TMODLOADER_POWERSHELL.

• Python 3.12+
• tModLoader installed (1.4.4.9 is what this is tested against)
• A mod embedding the trigger-file responder — copy responder/ into your mod's source tree and subclass DevResponder
• A .NET SDK, for api_search only — the index is built by a small C# tool. Everything else works without one.

Install

uv tool install tmodloader-mcp    # or: pip install tmodloader-mcp
                                  # or none at all: uvx tmodloader-mcp

The package is the Python half only. The responder is not on PyPI and could not usefully be — it is C# that compiles inside your mod — so it is vendored from responder/ in the repository, however you obtained the package.

Configuration

Every path is an environment variable. Two are required, because every plausible default for them names somebody's own install:

export TMODLOADER_SAVE_DIR="/mnt/c/Users/<you>/Documents/My Games/Terraria/tModLoader"
export TMODLOADER_MOD_SOURCE="$TMODLOADER_SAVE_DIR/ModSources/<YourMod>"

The required two have no default on purpose: a default pointing at the author's disk does not fail on yours — it resolves, worst case to something that exists, and the server drives an install you never chose. Both unset variables are reported together, so this costs one restart, not two.

TMODLOADER_WORLD_WIN is the world launch loads when you do not pass one. It has no default either; with neither set, launch refuses and lists the worlds actually in your save directory, with the Windows paths it wants. inventory answers the same question without launching anything.

The two describe one directory. If you set both to different places the server refuses to start and says so, rather than driving one and building the other.

Using it from Claude Code

A .mcp.json ships with the repository, so a session started in this directory finds the server:

{
  "mcpServers": {
    "tmodloader": {
      "command": "uv",
      "args": ["run", "tmodloader-mcp"],
      "env": {
        "TMODLOADER_SAVE_DIR": "${TMODLOADER_SAVE_DIR}",
        "TMODLOADER_MOD_SOURCE": "${TMODLOADER_MOD_SOURCE}"
      }
    }
  }
}

The two paths are read from your environment rather than written down — a committed config with real paths would be one person's paths in everybody's checkout. Export them where the client is launched, not only in an interactive shell: the substitution is the client's, against its own environment, and a value passed through as literal ${TMODLOADER_SAVE_DIR} is treated as absent and reported by that name. claude mcp list names any that are missing.

A project-scoped .mcp.json needs approving once — Claude Code will not run a server a repository asked it to run without being told to. Start claude in this directory and accept the prompt.

To drive the harness from the directory where you actually develop your mod, copy the block into that project's .mcp.json and point --directory at this checkout:

"args": ["run", "--directory", "/path/to/tmodloader-mcp", "tmodloader-mcp"]

Or, with the package from PyPI, no checkout at all:

"command": "uvx",
"args": ["tmodloader-mcp"]

The repository's own .mcp.json stays on uv run deliberately — inside this checkout you want the code in front of you, not the release behind it.

Known limits

Everything below is a fact about this repository rather than a plan; the struck-through history this section replaced lives in CHANGELOG.md, which is where a changelog belongs.

The thing most worth knowing about this project is that its hardest bugs were found by RUNNING it. Two clients overwriting each other's answers, a capture lock bounded by a guess, a dedicated server with no address to be told apart by, and — most recently — a save-snapshot feature whose entire premise turned out to be false when somebody finally measured it. The unit suite passed against every one of those. The changelog is the record.

It has only ever run on one install. One machine, one tModLoader (1.4.4.9), one world, one character. Every live check in tests/ drives a real game rather than a mock, which is the strongest evidence this project has — and it is still evidence from a single configuration. That is what the alpha classifier is for, and the first thing an outside user is likely to find is something install-specific.

Two dedicated servers racing for one trigger: observed once, not proven. Two servers on one save directory — different ports, different worlds, both polling the same trigger file — served six alternating addressed requests, each answered by the server it named, never by the other, always consumed (tests/live_race_check.py). One machine, one run: evidence the claim protocol holds under a real race, not a proof it always will.

There is no escape hatch, deliberately. Other harnesses ship reflect_invoke or execute_code. command is the answer here: it runs a mod's OWN registered ModCommands, which the mod already decided existed, named, and gave a usage line. That keeps every reachable action published, typed and refusable. Arbitrary evaluation would buy unlimited reach and throw that away, so a question nobody wrote a verb for still costs an edit, a rebuild and a relaunch.

A stopped session saves nothing. stop force-kills, so a run that changes the world usually leaves no trace on disk — measured, not assumed. Do not rely on that: a run long enough to autosave, or a graceful exit, does write. Take a save_snapshot before anything that mutates a world you care about.

_{MIT · what running it taught, in order · the protocol, written down · a template mod to start from}