Automated testing for Minecraft plugins and mods — drive a real Minecraft client from the command line, simulate player actions, and verify server-side behavior.
Unlike protocol-level bots, MC Pilot injects a mod into a genuine Minecraft client, so everything a real player sees — GUIs, scoreboards, titles, resource packs, anvils, villager trades — is observable and scriptable. Every operation is a CLI command with JSON output, which makes it a natural tool for AI coding agents (Claude Code, Codex, Cursor, …) to test the plugin they just wrote.
- Real client, zero intrusion — test plugins/mods as-is; the client mod executes actions and reports state, the server needs no changes
- AI-first design — JSON output by default, machine-readable
mct schema, bundled Coding Agent Skill - Wide version coverage — Minecraft 1.12.2 – 26.2, Fabric / Forge / NeoForge, 27 client variants
- Multiplayer testing — run multiple clients simultaneously (PvP, trading, cross-player interactions)
- Proxy networks — Velocity / BungeeCord topologies with automatic forwarding configuration
AI / Test Script
│ CLI commands (JSON in/out)
▼
┌─────────────────────────────┐
│ mct CLI (Node.js) │
│ client + server processes │
│ WebSocket command dispatch │
└────┬───────────────────┬────┘
│ process mgmt │ WebSocket
▼ ▼
Server MC Client + Mod
(plugin under (executes actions,
test) returns state)
Requirements: Node.js ≥ 20, plus a Java runtime matching the Minecraft version (Java 8 for Forge 1.12.2, Java 17 for 1.18–1.20, Java 21 for 1.21.x, Java 25+ for 26.x — pass --java <command> to client create, or set servers.<name>.java in mct.json, when it is not the default java).
npm install -g @kzheart_/mc-pilot# 1. Initialize a project in your plugin's directory (creates mct.json and run/)
mct init --name my-plugin
# 2. Put a server in run/ (mct runs servers, it does not download them)
mkdir -p run/paper-1.20.4/plugins
curl -fsSL -o run/paper-1.20.4/paper.jar "$(curl -fsSL https://fill.papermc.io/v3/projects/paper/versions/1.20.4/builds/latest | jq -r '.downloads."server:default".url')"
cp build/libs/my-plugin.jar run/paper-1.20.4/plugins/
# 3. Create a client and wire both into a profile in mct.json (see below)
mct client create fabric-1.20.4 --version 1.20.4
# 4. Start everything and wait until the client is in-world
mct up --eula
# 5. Drive the player, verify behavior
mct chat command "gamemode creative"
mct move to 100 64 100
mct block break 100 65 100
mct inventory get
mct gui screenshot
# 6. Tear down
mct downClients default to Simplified Chinese (zh_cn) with muted audio (--no-mute to opt out).
Client launch and stop refuse to terminate unrelated processes occupying the
configured WebSocket port. They report PORT_CONFLICT (exit code 5); stop the
conflicting process yourself or launch with a different --ws-port. --force
only replaces the tracked client, and does not override this ownership check.
Updated client mods accept server resource packs automatically by default. The policy is shared across Yarn, official-mapped 26.x and legacy Forge adapters. To test the confirmation or rejection flow, select a policy explicitly:
mct client launch fabric-1.20.4 --server 127.0.0.1:25565 --resource-pack prompt
mct resourcepack status
mct resourcepack accept
mct client wait-ready fabric-1.20.4
# Override the policy for a new connection
mct client reconnect --address 127.0.0.1:25565 --resource-pack reject--resource-pack accept|prompt|reject is also available on client create to
save an instance policy. An explicit launch policy overrides that saved policy.
Previously saved server rejections remain respected unless accept is selected
explicitly. Accepting a pack starts its normal Minecraft download and reload;
an acceptance response alone is not proof that the pack has finished loading.
The 1.20.4–1.21.11 and 26.x adapters expose vanilla download/reload outcomes
for wait-ready. Older Yarn adapters and Forge 1.12.2 report
resourcePackReadinessVerified: false: 1.12 download completion is
unverified, never fabricated as loaded, because its vanilla API does not
reliably expose reload failure. Actual texture application must be checked
separately on those adapters. A declared build variant is not a claim that every
loader combination has passed live testing. See the
resource-pack architecture and adapter contract.
The automatic-accept default is implemented in the client mod, so it also works
when launched by an older CLI. Use the matching updated CLI for
--resource-pack overrides and verified download/reload-aware wait-ready.
Project configuration — mct.json, profiles, server directories
mct init creates mct.json in the project root and a run/ directory, and adds run/ and .mct/ (screenshots) to .gitignore. Everything a test needs lives in the project: delete the directory and the environment is gone. Only shared downloads and client instances stay under ~/.mct.
{
"project": "my-plugin",
"defaultProfile": "1.20",
"profiles": {
"1.20": {
"servers": ["paper-1.20.4"],
"clients": ["fabric-1.20.4"]
}
},
"servers": {
"paper-1.20.4": { "java": "/path/to/java-17", "jvmArgs": ["-Xmx2G"] }
}
}Each name in servers is a directory under run/ holding a server jar. The optional top-level servers map sets per-server java, jvmArgs and jar (when a directory holds several jars). On its first start mct seeds a missing server.properties with online-mode=false and a free port; after that it only checks: server start refuses an un-accepted EULA (--eula accepts it), online-mode, or a busy port before launching.
mct up waits for every profile client to join a world. When that is not what you want:
mct up --skip-client-ready # launch clients but don't block on in-world checks
mct up --server-only-ok # server only; skip client launch entirelyNon-default versions — 26.x servers, legacy Forge 1.12.2
# Forge 1.12.2 requires Java 8; three Forge builds are selectable
mct client create forge-1.12.2 --loader forge --version 1.12.2 \
--forge-version 14.23.5.2864 --java /path/to/java-8Minecraft 26.x servers need Java 25: set "java" for that server in mct.json.
Use mct client search to discover supported client versions and loaders.
The npm package bundles the mc-pilot Coding Agent Skill. Install it into your agent(s) of choice — Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Windsurf, Copilot, or the standard Agents path:
mct skill installSelections persist in ~/.mct/skill-install.json and stay in sync automatically on future npm updates (mct skill sync / mct skill status to manage manually). For non-interactive installs, set MCT_SKILL_TARGETS=codex,claude (or all / none).
Agents can also introspect the full command surface at runtime:
mct schema # machine-readable CLI + WebSocket protocol schema
mct info # current project, active profile, state rootmct client launch and mct up include a cleanupReminder with commands to stop the clients when testing is finished. mct client list also shows this reminder when clients are still running, and mct up includes it in error details if client startup or readiness fails. These reminders appear in both JSON and --human output; clients are not automatically closed. Stopping a client releases its running resources but leaves its files and download cache on disk.
Servers, worlds and screenshots live inside each project (run/, .mct/), so deleting a project or a run/<name> directory frees them. What remains under ~/.mct is shared: client instances and the download cache. mct cache clean reports what can go and only deletes with --yes:
mct cache clean # dry run: unused client runtimes, old server-jar cache
mct cache clean --clients-idle 30d # also clients not launched for 30 days
mct cache clean --clients-idle 30d --yesClient runtimes still used by a remaining client, and running clients, are never removed.
All commands output JSON by default; add --human for human-readable output. Run mct <command> --help for details.
| Area | Commands |
|---|---|
| Project | init up down use info schema cache |
| Instances | server (start/stop/status/exec) · client (search/create/launch/stop/wait-ready) · skill |
| Movement & world | move look position rotation block entity |
| Chat & UI | chat gui sign book hud resourcepack |
| Items & stations | inventory craft recipe anvil enchant trade |
| Combat & input | combat input |
| Observation | status screenshot screen image events wait wait-log record |
Global options:
--project <id> Project ID (default: derived from cwd)
--profile <name> Profile name (default: project's defaultProfile)
--client <name> Target client (required with multiple clients)
--human Human-readable output (default: JSON)
mct client create p1 --version 1.20.4 --ws-port 25560
mct client create p2 --version 1.20.4 --ws-port 25561
mct client launch p1 --server 127.0.0.1:25565 --account Fighter1
mct client launch p2 --server 127.0.0.1:25565 --account Fighter2
mct client wait-ready p1 && mct client wait-ready p2
mct --client p1 chat command "pvp challenge Fighter2"
mct --client p2 chat wait --match "challenge" --timeout 5
mct --client p2 chat command "pvp accept"
mct --client p1 combat kill --nearest --type player
mct --client p2 status healthmct chat command "shop"
mct gui wait-open --timeout 5
mct gui snapshot # inspect slot layout
mct gui click 11 # click a category
mct gui wait-update --timeout 3
mct gui click 13 --button left # buy an item
mct chat wait --match "purchased" --timeout 5
mct gui close
mct inventory get # verify item arrivedmct chat command "tp TestPlayer 100 64 100"
mct block break 100 64 100
mct chat history --last 3 # expect a permission-denied message
mct block get 100 64 100 # block must still exist
mct move to 200 64 200
mct block break 200 64 200
mct block get 200 64 200 # block must be gone# exec returns the lines the command logged, plus a cursor
mct server exec "data get entity @p Health" # → data.output, data.cursor
# Wait for something the server logs later; --after also matches lines already written
C=$(mct server status | jq '.data.servers[0].logCursor')
mct chat command "shop buy diamond"
mct wait-log --grep "purchased diamond" --after "$C" --timeout 10
# Anything else: read the server's own log
grep -E "ERROR|Exception" run/paper-1.20.4/logs/latest.logMore recipes — crafting, enchanting, screenshots
mct block interact 12 80 34 # open the crafting table
mct craft --recipe '[["oak_planks",null,null],["oak_planks",null,null],[null,null,null]]'
mct inventory get # result is in inventoryThe legacy 9-slot object form '{"slots":[...]}' is also accepted and normalized.
mct block interact 16 80 40
mct gui click 36 --button left # pick up sword from inventory
mct gui click 0 --button left # place in enchant input slot
mct gui click 37 --button left # pick up lapis
mct gui click 1 --button left # place in lapis slot
mct enchant --option 0 # 0=top, 1=middle, 2=bottomRecord Minecraft's own framebuffer through the mod, with silent H.264 MP4 output by default. The default is native 1920×1080 at a requested 30 fps; the framebuffer must actually match, with no upscaling or desktop capture.
mct record doctor # existing FFmpeg + libx264, no automatic download
mct record status --client <client> # running mod's encoder/backend capability
mct record start shop-demo --client <client>
# Run the test; recording continues after the CLI exits
mct record stop --client <client> # wait for MP4 finalization
mct record view shop-demo --client <client> --probeThese changes are released in CLI 0.20.0 with matching Mod 0.10.0 artifacts. Follow the release installation instructions; upgrading the CLI does not replace the Mod JAR in an existing client.
An opt-in Minecraft 1.20.1 game-audio prototype adds AAC stereo from the game's actual OpenAL mix. Set the game JVM argument -Dmct.record.audio=true before game startup and keep game audio unmuted; this does not capture a microphone or system audio. The latest audio and visual hand-feedback demonstration was built and tested on Fabric 1.20.1 only. Forge/NeoForge 1.20.1 inherit the source but have not received this audio validation. See audio setup and validation scope and measured results; the earlier 27-variant silent-video validation predates the latest hand/audio changes.
Use mct client launch <client> --width 1920 --height 1080 to request that window size explicitly; HiDPI framebuffer dimensions can differ. Configure an existing encoder with --record-ffmpeg /path/to/ffmpeg. Files live in the selected client's gameDir/recordings, and existing names are never overwritten. Check finalized, capturedFps, dropped/duplicate counts, and the returned outputPath; a 30 fps container alone does not prove 30 distinct captured frames per second. See recording setup, limits and review.
# Screenshots use a longer timeout and one retry by default; tune if the client is slow
mct screenshot --timeout 45 --retries 2 --output ./screenshots/check.pngMore runnable examples live in examples/ (shop, PvP, WorldGuard, proxy networks).
✅ verified ·
| Minecraft | Fabric | Forge | NeoForge |
|---|---|---|---|
| 1.12.2 | — | ✅ | — |
| 1.18.2 | ✅ | ✅ | — |
| 1.20.1 | ✅ | ✅ | ✅ |
| 1.20.2 | ✅ | ✅ | |
| 1.20.4 (default) | ✅ | ✅ | ✅ |
| 1.21.1 | ✅ | ✅ | ✅ |
| 1.21.4 | ✅ | ✅ | ✅ |
| 1.21.11 | ✅ | ✅ | ✅ |
| 26.1 | ✅ | ✅ | ✅ |
| 26.2 | ✅ | ✅ | ✅ |
Version notes:
- 26.1 servers — Paper publishes no exact
26.1artifact; the Fabric 26.1 client is verified against Paper 26.1.1 build 29 and 26.1.2 build 74. Paper 26.2 build 60 and Vanilla 26.2 are verified with the Fabric 26.2 client. - NeoForge 1.20.2 — NeoForge 20.2 clients cannot join Paper/Bukkit-family 1.20.2 servers at all (upstream
Invalid payload REGISTER!handshake incompatibility, fixed in NeoForge 20.4). The variant works against vanilla servers; this is why it stays at limited validation. - Forge 1.12.2 — built with the legacy Java 8 toolchain; Forge builds 14.23.5.2859 / 2860 / 2864 are selectable via
--forge-version. The legacy mod implements the full protocol (chat, status, movement, blocks, entities, combat, inventory, GUI interaction, crafting/anvil/enchant/trade, signs, books, HUD, screenshots, keyboard/mouse input, reconnect), verified end-to-end against a vanilla 1.12.2 server. Onlyinput scrollis unavailable (LWJGL2 offers no event injection). On Apple Silicon, use an x86_64 Java 8 runtime under Rosetta (Minecraft 1.12.2 ships LWJGL2 x86_64 natives only).
git clone https://github.com/kzheart/mc-pilot.git
cd mc-pilot
npm ci
npm run test:cli # CLI unit tests
npm run test:e2e # CLI system E2E tests
npm run check:protocol # verify CLI/protocol schema sync
npm run test:real # full suite against a real client (slow)
cd client-mod && ./gradlew build # build client mod (all modern variants)
cd client-mod/legacy && ./gradlew build # Forge 1.12.2 variant (requires Java 8)mc-pilot/
├── cli/ # CLI tool (TypeScript)
├── client-mod/ # Fabric/Forge/NeoForge client mod (Java, multi-version modules)
│ ├── legacy/ # Forge 1.12.2 (Java 8 toolchain)
│ └── mc26/ # Minecraft 26.x variants (Java 25 toolchain)
├── protocol/ # WebSocket protocol definitions
├── examples/ # Example test scripts
├── scripts/ # Internal E2E test scripts
└── paper-fixture/ # Internal test fixture Paper plugin