mc-agent-mcp
English | 简体中文
A Minecraft Fabric mod that runs a Model Context Protocol (MCP) server inside the game client, so an AI agent (Claude, DeepSeek, or any MCP client) can see the world and play survival on its own: walk, mine, build, fight, eat, craft, smelt, use chests and chat.
Demo video (Chinese, 4 min, download): DeepSeek V4 Flash goes from an empty inventory to a stone sword, builds a shelter before night, and fights mobs with survival reflexes.
Features
- 29 tools covering perception, movement, interaction, inventory, crafting and chat (reference).
- Survival reflexes for slow models: the mod defends, evades creepers, eats, equips armor and swims up every tick (50 ms), so an agent that needs seconds per turn is not killed while it thinks (details).
- Built for LLMs: readable ASCII block maps, nearest-first entity lists, recipe lookup that says whether a crafting table is needed, errors that tell the agent what to do next ("out of reach; move closer").
- Survival-correct actions: mining takes real tool-speed time, crafting goes through the recipe book like a player, reach is enforced, all actions are normal client packets.
- Fast perception: section-level block scanning, compact
rleencoding, exact block-change tracking pushed over SSE. - Owner controls: loopback-only, Bearer auth,
Originchecks, per-category permissions, per-tool disabling and rate limits.
Quick start
- Install Fabric Loader for 1.21.11 and Fabric API.
- Download
mc-agent-mcp-<version>.jarfrom Releases (or build it) and drop it into.minecraft/mods/:./gradlew build # -> build/libs/mc-agent-mcp-<version>.jar - Start the game once. The mod writes
config/mcagent.jsonwith a randomauthTokenand logs the endpoint. - Connect your MCP client:
URL: http://127.0.0.1:27890/mcp Header: Authorization: Bearer <authToken from config/mcagent.json>
Claude Code
TOKEN=$(grep authToken ~/.minecraft/config/mcagent.json | cut -d'"' -f4)
claude mcp add --transport http minecraft http://127.0.0.1:27890/mcp \
--header "Authorization: Bearer $TOKEN"
Join a world and ask, for example: "Collect some oak logs, craft a wooden pickaxe and mine 10
cobblestone." The initialize response includes a short playbook (instructions) that
clients put in the model's context: the observe → act loop, yaw directions, reach limits and
how crafting works.
Other clients (Claude Desktop via mcp-remote, Cursor, custom agents, …) use the same URL and
header.
DeepSeek Harness (DSH)
The dsh-plugin-minecraft bundle connects DSH to the mod with no
configuration (it finds the port and token itself, including HMCL/PCL version folders):
dsh plugin --profile web add dsh-plugin-minecraft
Tested end to end: DeepSeek V4 Flash in dsh headless, starting from an empty inventory next to
two oak trees, collected logs and crafted a crafting table and a wooden pickaxe in 69 s (17 steps).
Example agent (DeepSeek or any OpenAI-compatible API)
examples/deepseek_agent.py is a standalone agent loop (Python
standard library only). It injects a fresh observe into every turn, keeps the context short and
lets the model call several tools per turn, which suits fast, inexpensive models:
export DEEPSEEK_API_KEY=sk-...
python3 examples/deepseek_agent.py --model <model id from your provider> \
--goal "Gather wood, craft a wooden pickaxe, then mine 10 cobblestone."
# --base-url for other OpenAI-compatible APIs, --config if .minecraft is elsewhere
Smoke test with curl
TOKEN=$(grep authToken ~/.minecraft/config/mcagent.json | cut -d'"' -f4)
call() { curl -s -X POST http://127.0.0.1:27890/mcp -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d "$1"; echo; }
call '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
call '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
call '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"observe","arguments":{}}}'
call '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_blocks","arguments":{"format":"layers","radius":9}}}'
Configuration
config/mcagent.json (in the game directory) is rewritten on every start with all keys, so new
options show up automatically. Edit it while the game is closed.
{
"enabled": true,
"port": 27890,
"bindAddress": "127.0.0.1",
"authToken": "<generated>",
"allowCommands": false,
"disablePauseOnLostFocus": true,
"permissions": { "perception": true, "movement": true, "interaction": true, "inventory": true, "chat": true },
"disabledTools": [],
"reflexes": { "autoDefend": true, "evadeCreepers": true, "chargeRanged": true, "autoEat": true,
"autoArmor": true, "escapeFluids": true, "interruptOnDamage": true, "eatBelowFood": 14 },
"rateLimits": {
"global": { "perSecond": 20, "burst": 40 },
"perception": { "perSecond": 0, "burst": 0 },
"movement": { "perSecond": 10, "burst": 20 },
"interaction": { "perSecond": 10, "burst": 20 },
"inventory": { "perSecond": 20, "burst": 40 },
"chat": { "perSecond": 0.5, "burst": 3 }
}
}
Hidden tools are removed from tools/list, so the model never tries them; calling one anyway
returns an error that names the config key. A rate-limited call returns isError with
retryAfterMs. stop and ping are control tools: never hidden, never limited, so an
agent can always halt. The chat default (one message per 2 s, burst 3) stays well under
vanilla's spam kick.
Typical setups:
- Watch-only (the agent can look but not act): set
movement,interaction,inventoryandchattofalse. - Peaceful helper on a shared server:
"disabledTools": ["attack_entity"],chat: false.
Tools
Categories drive permissions, rate limits and the MCP annotations (readOnlyHint for
perception, destructiveHint for interaction and inventory).
Survival reflexes
An LLM needs seconds per decision; a zombie hits every second and a creeper explodes 1.5 s after it starts hissing. So the mod reacts on its own, every tick, between the agent's turns:
observe reports threats (hostiles within 16 blocks, nearest first, hissing for creepers)
and events (damage taken, what the reflexes did, kills) since the previous observe; movement
results carry threats too. Each reflex only runs if the owner allows the tool it imitates, so
permissions.interaction: false or "disabledTools": ["attack_entity"] also disables
auto-defence. The agent can switch reflexes off with set_reflexes to fight by hand.
Measured on a Normal-difficulty server at night with an idle agent (stone sword and bread in the hotbar, no armor), mobs spawned 5 blocks away:
Reading blocks
get_blocks takes center [x,y,z] (default: the player), size [sx,sy,sz] (default
[32,32,32]) or radius, and format. At most 96³ cells per call.
layers: one ASCII map per Y level (layers[0]is the top) plus alegend. An LLM can read it directly.rle(default): smallest.palettemaps index → block id;datais base64 of int32 runs in y-major, then z, then x order, each run(runLength << 12) | paletteIndex.json: explicit{x,y,z,b}list with air skipped. Largest, but self-describing.
scan_blocks takes blocks (e.g. ["diamond_ore"]), radius (default 16, max 32) and max
positions per block type.
Block-change tracking
subscribe_blocks {action:"start", radius:16} -> baseline is built
get_block_changes {} -> {changed, full, resync, changes:[{pos,from,to}]}
Or open GET /mcp with the same token for Server-Sent Events:
event: message
data: {"jsonrpc":"2.0","method":"notifications/mcagent/block_diff","params":{"changed":1,"changes":[{"pos":[12,64,-3],"from":"-","to":"minecraft:stone"}]}}
- The first result after
startisfull: true(baseline only).resync: truemeans more than 4096 changes piled up; re-read withget_blocks. - The cube is anchored to 16-block boundaries and re-anchors when the player crosses a chunk
border (also reported as
full). Chunks loading in are re-baselined silently. - Use either SSE or polling per session: while a stream is open, diffs go to the stream.
A client that disconnects without
DELETE /mcpis only noticed at the next heartbeat (15 s).
Crafting and containers
get_recipes {item:"wooden_pickaxe"} -> station "crafting_table", ingredients
craft {item:"oak_planks", count:12} -> 2x2 grid, no table needed
place_block {pos} + interact_block {pos} -> open the crafting table
craft {item:"wooden_pickaxe"} -> made in the 3x3 grid
interact_block {furnace}
transfer_items {to:"container", item:"raw_iron"} -> goes to the input slot
transfer_items {to:"container", item:"coal"} -> goes to the fuel slot
transfer_items {to:"player", item:"iron_ingot"} -> take the output
craft places the recipe (the server fills the grid), waits for the result and shift-clicks it,
repeating until count is reached. Only unlocked recipes can be placed, as in vanilla
survival; anything else can be done by hand with click_slot.
How actions run
Timed actions (move, break_block, use_item with ticks, craft) advance on game ticks
and the call returns when they finish (move also has wait:false). Starting an action of the
same kind replaces the running one; stop cancels everything.
- Movement is injected right after vanilla reads the keyboard (
KeyboardInputMixin), so it works while the window is unfocused. - While mining, vanilla's per-tick
continueAttackis skipped (MinecraftMixin): with the attack key up it would reset break progress every tick. - Reach is checked up front (~4.5 blocks for blocks, ~3 for entities) and reported as an actionable error.
Security
- Binds to
127.0.0.1by default; every request needs the Bearer token (constant-time compare). - Requests with a non-loopback
Originheader get 403, which blocks DNS-rebinding attacks from web pages. - POST bodies over 1 MiB get 413.
- Chat
/commandsare off by default; permissions and rate limits are described above.
Design notes
- Threads: HTTP workers only validate and route. All world access runs on the client thread
(
GameBridge); multi-tick actions are driven fromEND_CLIENT_TICKand the HTTP thread waits on a future. SSE streams get their own threads. - Scanning walks
LevelChunkSections directly and skips empty sections instead of callinggetBlockStateper cell. - Change detection hooks both
ClientLevel.setBlock(client predictions) andsetServerVerifiedBlockState(server updates, which bypasssetBlock), marks the chunk dirty, and re-scans only that chunk. Snapshots are sparse; block states are interned, so diffs are pointer compares.
Encoding a 48³ terrain-like volume (110,592 cells) off-thread (checks/CodecBench.java):
Development
Layout
src/main/java/com/mcagent/mcp/ (no Minecraft client classes)
config/McAgentConfig.java config file, defaults, -> ToolPolicy
server/ JSON-RPC, MCP protocol, Streamable HTTP transport, SSE
tools/ McpTool SPI, registry, ToolCategory, ToolPolicy, RateLimiter,
Args (validation), Schema (builder)
src/client/java/com/mcagent/mcp/client/
McAgentClient.java entrypoint: wiring, lifecycle, agent playbook
GameBridge.java client-thread dispatch
ChatLog.java bounded chat log
control/AgentControl.java timed actions: held keys, use key, mining, menu scripts, go_to
reflex/ per-tick survival reflexes + pure weapon/food/armor choice
blocks/ scanner, codecs, change tracker
inventory/ menu reader, recipe book, crafting task, pure transfer logic
mixin/ ClientLevel, KeyboardInput, Minecraft hooks
tools/ one class per tool
checks/ offline test suite
Offline checks
./checks/run.sh
In-game testing
The offline suite cannot cover mixins at runtime or real gameplay. Run a local offline-mode server and the dev client:
# 1. server (Loom has already cached the jar), flat world, peaceful
mkdir -p /tmp/mcsrv && cd /tmp/mcsrv
cp <repo>/.gradle-home/caches/fabric-loom/1.21.11/minecraft-server.jar . # or ~/.gradle/caches/...
echo eula=true > eula.txt
printf 'online-mode=false\nserver-port=25599\nlevel-type=minecraft\\:flat\ndifficulty=peaceful\nspawn-protection=0\n' > server.properties
java -jar minecraft-server.jar --nogui # console: /give, /setblock, /summon to stage scenarios
# 2. dev client (set onboardAccessibility:false in run/options.txt first, or quick play stalls)
./gradlew runClient --args="--quickPlayMultiplayer 127.0.0.1:25599"
Then call tools as in the curl smoke test, using the token in run/config/mcagent.json. Every
tool has been exercised this way in survival.
Roadmap
- M0–M3 ✅ skeleton, HTTP/JSON-RPC transport, block engine with change tracking and SSE
- M4 ✅ perception: entities, inventory, chat
- M5 ✅ actuation: move, look, mine, place, interact, attack, use, chat, respawn, stop
- M6 ✅ containers and recipe-book crafting
- M7 ✅ hardening: permissions, rate limits, request limits, tool annotations, bilingual docs
- M8 ✅ playable by fast/cheap models: survival reflexes, interrupt on damage,
go_to,batch, threats/events inobserve, example DeepSeek agent - M9 ✅ DeepSeek Harness plugin;
layerslabelled withlayerY;go_tostops next to solid targets and names what blocks it - Next: optional
pathfind_tovia Baritone (LGPL, kept as an external dependency)
License
MIT. Fabric Loader/Loom are Apache-2.0, the MCP specification and SDKs are MIT. Baritone (LGPL) would only ever be an optional external dependency.