musharna/tmodloader-mcp

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//Documents/My Games/Terraria/tModLoader"
export TMODLOADER_MOD_SOURCE="$TMODLOADER_SAVE_DIR/ModSources/"

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.