MCTest
A dev-only Minecraft client mod (Fabric + NeoForge, Minecraft 26.1.2, 26.2 and 26.3) plus an MCP server, so Claude Code (or any coding agent, or your own scripts) can drive a running Minecraft client the way Playwright drives a browser: open worlds, click GUIs, press keys, walk, mine, place, craft, fight, run commands, inspect blocks, entities and inventories, read logs and take screenshots. The main use is testing your own mods.
Documentation: https://mctest.coolerpromc.com/
Claude Code ──stdio/MCP──▶ mcp/ (Node) ──WebSocket JSON-RPC──▶ MCTest mod in your dev client (127.0.0.1:25599)
- Loopback only. The control servers bind to
127.0.0.1. On the client, MCTest drives the game; on a dedicated server (optional, see Testing on a dedicated server) it exposes the server side. - Never ship it. Add it to your mod as a dev-runtime dependency (see below). It is not bundled into your jar or published POM.
- Everything runs through vanilla code paths: input goes through Minecraft's own mouse/keyboard handlers and key
mappings, and interactions go through
MultiPlayerGameMode, so the server validates them as for a real player.
1. Use MCTest in your mod
Where to get it
MCTest is published to https://maven.coolerpromc.com/releases/ as
com.coolerpromc.mctest:mctest-<loader>-<minecraft version>:<version>, for Minecraft 26.1.2, 26.2 and 26.3.
The snippets below use that repository. If you're changing MCTest itself, run ./gradlew publishToMavenLocal and use
mavenLocal() instead to pick up your local build.
Latest releases, updated automatically from the Maven repository. Pick the row for your Minecraft version:
The snippets below are for 26.3. For another Minecraft version, replace the artifact and version with the
ones from its row (for example mctest-fabric-26.1.2:26.1.2.1).
Fabric (Loom), in your mod's fabric/build.gradle
repositories {
maven { url = 'https://maven.coolerpromc.com/releases/' }
}
dependencies {
// Dev-only: on the runClient classpath, never in your jar or POM.
localRuntime("com.coolerpromc.mctest:mctest-fabric-26.3:26.3.0.3") { transitive = false }
}
localRuntime is Loom's dev-runtime configuration. transitive = false stops MCTest's own fabric-api /
fabric-loader runtime dependencies from overriding your versions.
NeoForge (ModDevGradle), in your mod's neoforge/build.gradle
ModDevGradle has no built-in localRuntime, so declare one:
repositories {
maven { url = 'https://maven.coolerpromc.com/releases/' }
}
// Runtime-only in dev, never published.
configurations {
localRuntime
runtimeClasspath.extendsFrom localRuntime
}
dependencies {
localRuntime("com.coolerpromc.mctest:mctest-neoforge-26.3:26.3.0.3") { transitive = false }
}
Both setups were verified with a MultiLoader-template mod: MCTest loads in runClient on both loaders and does not
appear in the built jar or the generated POM.
Changing the port (optional)
Default is 25599. To run several clients at once, or avoid a clash, set a system property on the client run:
// Fabric: loom { runs { client { vmArg('-Dmctest.port=25600') } } }
// NeoForge: neoForge { runs { client { systemProperty('mctest.port', '25600') } } }
Then give the MCP server the same port (MCTEST_PORT, below).
2. Set up the MCP server
Requires Node 22+. The server is published to npm as mctest-mcp, so
there's nothing to clone or build. Register it with Claude Code once, for all projects:
claude mcp add mctest --scope user -- npx -y mctest-mcp
For a client on a different port:
claude mcp add mctest --scope user -e MCTEST_PORT=25600 -- npx -y mctest-mcp
To share it with everyone working on a mod, commit a .mcp.json in that mod's repository:
{
"mcpServers": {
"mctest": { "command": "npx", "args": ["-y", "mctest-mcp"] }
}
}
The server connects lazily and reconnects after the game restarts, so it can be registered once and left running.
Start your client with ./gradlew :fabric:runClient (or :neoforge:runClient), or let the agent start it with
mc_launch; the agent then calls mc_wait_ready. When it has finished testing it calls mc_close_all, which closes
every client and server; games started with mc_launch / mc_server_launch are also closed when the MCP session ends.
To run the server from this checkout instead (when changing it): cd mcp && npm install, then register
node <path-to-checkout>/mcp/dist/index.js. Publish a new version with npm version patch && npm publish from mcp/.
Testing on a dedicated server
Multiplayer bugs (missing packets, client/server desync, code that only works in singleplayer because both sides share
a JVM) only show up against a real dedicated server. MCTest runs on the server too: the same localRuntime dependency
puts it on runServer, where it opens a second control API on ws://127.0.0.1:25598/ (-Dmctest.serverPort=...)
that the mc_server_* tools talk to.
./gradlew :fabric:runServer # or :neoforge:runServer (first run: accept the EULA in runs/server/eula.txt)
./gradlew :fabric:runClient # in a second terminal
Then the agent calls mc_server_wait_ready, mc_wait_ready and mc_connect (default localhost). From there client
tools drive the player as usual, and the server tools show and change the authoritative side:
mc_server_command "setblock 10 64 10 mymod:grinder" → mc_connect → mc_use_on (open it) → mc_click_slot …
→ mc_server_block {x:10,y:64,z:10} (server NBT) vs mc_block {…, source:"client"} (what the client was sent)
→ mc_server_wait_for "log:Grinder finished" → mc_server_logs {level:"WARN"}
In a development environment MCTest makes a dev server usable by dev clients:
- Offline mode. Dev clients have no Mojang session, so the server skips authentication and does not require signed
chat, whatever
server.propertiessays. Opt out with-Dmctest.onlineMode=true. - No whitelist. New 26.x servers whitelist by default; MCTest turns it off at startup (as
/whitelist offwould)./whitelist onstill works afterwards. Keep it with-Dmctest.whitelist=true. - Auto-op. Players are opped when they join, so
mc_commandworks from the client. A test that deops a player is respected until they rejoin. Turn off with-Dmctest.autoOp=false(for permission tests).
The server API has no singleplayer equivalent and is not started in the integrated server: in singleplayer the client
API already reads the integrated server directly (mc_block, mc_time_*).
A typical agent session
Start the NeoForge client in the background, wait until it's ready, create a flat creative test world, give me a
mymod:grinder, place it, put 8 iron ore in it, wait 200 ticks, and check that it output iron dust. Screenshot the GUI.
which turns into calls like:
mc_wait_ready → mc_world_create {name:"grinder-test", flat:true}
→ mc_command "give @s mymod:grinder" → mc_player (find the slot) → mc_select_slot
→ mc_use_on {x,y,z, face:"up"} (place) → mc_use_on (open GUI) → mc_wait_for "screen:GrinderScreen"
→ mc_snapshot → mc_click_slot … → mc_wait_for "ticks:200" → mc_block (block-entity NBT) / mc_snapshot
→ mc_screenshot → mc_logs {level:"WARN"} (anything go wrong?)
3. Tools / methods
Each MCP tool mc_* wraps one method of the mod's WebSocket API (shown in brackets). Coordinates in GUI methods are
GUI-scaled (what mc_snapshot reports). 20 ticks = 1 second.
Dedicated-server tools (the server's own API, port 25598):
Playing like a player
The skill tools build on the primitives and behave the way a person plays, which makes them useful for realistic survival-style tests of your mod. They are not shortcuts:
- Movement.
mc_gotonever teleports. It plans a path (walk, diagonal, 1-block jumps, drops of up to 3 blocks, swimming; it avoids lava, fire, magma, cactus and berry bushes), then steers with the real movement keybinds. The camera turns at most 40° per tick, it sprints on straight stretches, and it replans when stuck. - Mining.
mc_collectonly targets blocks a player could see (an exposed face, in line of sight), prefers walls over floors, never digs out the block you stand on or the steps of a staircase you dug, and refuses up front if nothing in your inventory can harvest the block. Drops are walked over and picked up. - Digging.
mc_digwon't dig through tables, chests, furnaces or machines, and looks for lava and water before opening a space. - Fighting.
mc_fightrespects the attack cooldown, so damage is what a real player would deal. - Crafting.
mc_craftuses the recipe book, so recipes must be unlocked, exactly as in survival. - Lockstep.
mc_lockstepremoves the agent's thinking time from the game: the world runs only while an action is in progress.
scripts/survival-test.mjs uses only these player actions, in a world with cheats off,
to go from bare hands to a stone pickaxe: find trees, chop logs, craft planks, a table, sticks and a wooden pickaxe,
place the table, dig a staircase down to stone, mine cobblestone, craft a stone pickaxe, and hunt an animal. On random
terrain it succeeded on 4 of 5 seeds tried. The failures were terrain dead ends (for example being stuck at the bottom
of a hole with no exposed stone), which is where pathfinding that can place blocks (pillaring, bridging) would help.
Things worth knowing
-
Errors come to you. After every tool call the MCP server checks the game's log for new ERROR lines and appends them to the result, so an exception your mod throws shows up right after the action that caused it.
mc_logshas the full stacks. If the game crashes, the next call fails with a hint to usemc_crash_report. -
GameTests.
mc_gametest_run {tests:"mymod:*"}runs your mod's GameTests (registered through the Fabric or NeoForge GameTest API) in the open world and returns each result, so an agent can write a GameTest, rebuild, and check it in one loop. Use a flat test world: tests are placed near the world spawn. -
Keybind actions apply on the next tick.
mc_key {key:"e"}returns before the inventory opens. Follow it withmc_wait_for {condition:"screen:InventoryScreen"}. -
Screen class names are the real, unobfuscated ones (
InventoryScreen,CreativeModeInventoryScreen,CraftingScreen, your mod's screen class).screen:also matches superclasses, for examplescreen:AbstractContainerScreen. -
Two slot numberings. Container slot numbers are menu indices from
mc_snapshot(crafting table: 0 = result, 1–9 = grid, 10–45 = inventory).mc_playerinventory slots are inventory indices (0–8 hotbar, 9–35 main, 36+ armor/offhand). -
Pause on lost focus is turned off. The game window is usually not focused while an agent drives it, and vanilla would otherwise open the pause menu every time a screen closes. MCTest turns
pauseOnLostFocusoff in memory. To keep vanilla behaviour, launch with-Dmctest.pauseOnLostFocus=true. -
Logs from before MCTest loads. On Fabric MCTest attaches in
preLaunch, before any mod initializes. On NeoForge, lines logged before MCTest is constructed are imported fromlogs/latest.log(flaggedbackfilled: true), so your mod's startup errors are visible on both loaders. -
Tutorial hints are skipped. Toasts like "Look around" would otherwise cover screenshots. Use
-Dmctest.tutorial=trueto keep them. -
Input is SDL3 from 26.3. Raw key numbers for
mc_keyare SDL scancodes on 26.3 and GLFW key codes on 26.1.2/26.2. Use names, which work on every version. -
Your mouse is left alone. Vanilla captures the OS cursor whenever a screen closes in-world and warps it to the window centre whenever one opens, so an agent opening and closing screens or entering worlds would keep trapping or yanking your mouse while you work in another app. With MCTest, the game only captures or moves the cursor within 2 seconds of your own click or key press in its window. MCTest's synthetic input never counts. Click into the game to play by hand as usual.
statusreportswindowFocusedandmouseGrabbed. Use-Dmctest.mouseWarp=truefor vanilla behaviour.
4. Raw protocol
WebSocket on ws://127.0.0.1:<port>/. Send {id, method, params}, receive {id, result} or
{id, error: {message, type, stack}}. Requests run concurrently and responses are matched by id.
const ws = new WebSocket('ws://127.0.0.1:25599/');
ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'status', params: {} }));
ws.onmessage = (e) => console.log(JSON.parse(e.data));
scripts/lib.mjs is a tiny promise client for Node 22+ (no dependencies).
5. Developing MCTest itself
Publishing a release
./gradlew publish uploads the common, Fabric and NeoForge artifacts to the repository given by the maven_url,
maven_username and maven_password Gradle properties. Keep them in your user-level ~/.gradle/gradle.properties,
never in this repo:
maven_url=https://maven.coolerpromc.com/releases/
maven_username=...
maven_password=...
Bump version in gradle.properties first; release repositories usually refuse to overwrite an existing version.
common/ all logic (vanilla code only): server/, rpc/, methods/, capture/, tick/, mixin/
fabric/ entrypoints + tick hook (ClientTickEvents) + platform service
neoforge/ entrypoint + tick hook (ClientTickEvent.Post) + platform service
mcp/ MCP server (TypeScript)
scripts/ end-to-end test scripts
Every game-state access hops to the render thread with Minecraft.execute() and completes a CompletableFuture;
nothing blocks the render thread. Waits are checked on each client tick.
One command builds and launches the client and a dedicated server for each loader, runs the suites below, and
quits the game afterwards (game output in build/test-logs/):
node scripts/run-tests.mjs # both loaders, all default suites
node scripts/run-tests.mjs fabric --suites step4,mcp
Or run a single suite against a client you started yourself (./gradlew :fabric:runClient or :neoforge:runClient):
node scripts/ws-test.mjs # status + screenshot smoke test
node scripts/step4-test.mjs # commands, player/block/entities, waitFor, logs
node scripts/step5-test.mjs # world create/join/leave/list/delete
node scripts/play-test.mjs # survival gameplay: walk, jump, place, mine, craft, eat, fight, milk
node scripts/skills-test.mjs # pathfinding, time freeze/step/lockstep, craft, collect, fight, dig
node scripts/survival-test.mjs [seed] # no-cheats run on real terrain: punch trees -> stone pickaxe
node scripts/cursor-test.mjs # screens open/close without the game capturing your mouse (Windows)
node scripts/server-test.mjs # dedicated server: also start ./gradlew :<loader>:runServer first
cd mcp && npm test # MCP server end to end over stdio
All of these pass on both Fabric and NeoForge for 26.3 (and for 26.2 and 26.1.2 on their branches). survival-test depends on the terrain around the spawn
point and passes on most seeds (see above).
License
MIT. See LICENSE.