minecraft-agent-body
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@minecraft-agent-body Collect some wood, craft a crafting table, and place it near me."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Minecraft Agent Body
Give an AI agent a bounded, inspectable body in Minecraft Java Edition.
This project is deliberately model-neutral. It does not contain an LLM, an API key, a Discord bot, or JNAIQ. Instead, it exposes one Mineflayer-controlled Minecraft player through:
MCP over stdio for Claude, Codex, and other MCP hosts.
A loopback-only JSON adapter for JNAIQ, Discord bots, and custom agent loops.
The model remains the decision-maker. The body reports observations and executes named actions.
Current status
Implemented and locally tested without Minecraft: configuration validation, event cursors, in-band tool failures, MCP startup, loopback-only HTTP transport, and package checks.
Requires your live environment to validate: joining your server, Microsoft device-code login, pathfinding, mining, crafting, placing, combat, eating, and sleeping. Minecraft protocol support follows Mineflayer's supported versions.
Related MCP server: Minecraft MCP Server Pro
Requirements
Node.js 20 or newer
A Minecraft Java server you are allowed to join
For online-mode servers, a Microsoft account that owns Minecraft Java Edition
An MCP host or a custom program that can call the JSON adapter
Install
git clone https://github.com/several-dozen-lizards/minecraft-agent-body.git
cd minecraft-agent-body
npm install
npm testCopy .env.example to .env if your launcher loads environment files, or set the variables in the MCP host configuration. The program does not parse .env by itself so secrets stay under the control of the host that launches it.
Fast local test
Start a local Minecraft Java server in offline mode, then:
npm run start:httpIn another terminal:
curl http://127.0.0.1:31822/health
curl -X POST http://127.0.0.1:31822/call -H "Content-Type: application/json" -d '{"name":"minecraft_connect","arguments":{}}'
curl -X POST http://127.0.0.1:31822/call -H "Content-Type: application/json" -d '{"name":"minecraft_status","arguments":{}}'PowerShell equivalents are in docs/QUICKSTART_WINDOWS.md.
Tools
The first public cut includes:
minecraft_connect, minecraft_disconnect, minecraft_status, minecraft_inventory, minecraft_events, minecraft_look, minecraft_goto, minecraft_follow, minecraft_stop, minecraft_collect, minecraft_dig, minecraft_place, minecraft_craft, minecraft_equip, minecraft_eat, minecraft_sleep, minecraft_attack, and minecraft_say.
minecraft_say refuses messages beginning with /. This prevents the chat tool from silently becoming a server-operator console.
Connect a brain
Design promises
The core has no provider SDK and no model preference.
Credentials are read from the launching environment and never returned by a tool.
The JSON adapter refuses non-loopback binds.
Long actions do not silently stack; a second action receives
BUSYuntil the current action finishes orminecraft_stopis called.Optional coordinate bounds constrain movement and world mutation.
Every action returns structured success or a structured, actionable error.
Events and action receipts can be consumed incrementally by cursor.
Not the same as the 141-hour visual benchmark
That experiment had the model operate ordinary keyboard and mouse controls from visual observations. This project gives the agent a structured Minecraft body, which is more reliable and dramatically cheaper to run. A later optional visual module can add screenshots without making them the only sense available.
License
MIT. Minecraft is a trademark of Microsoft/Mojang; this independent project is not affiliated with or endorsed by them.
Available Tools
18 toolsminecraft_attackA
Approach and strike one nearby visible entity by name.
Inputs: target (required).
minecraft_collectC
Find and dig one or more nearby blocks by block name.
Inputs: block (required), count, maxDistance.
minecraft_connectC
Connect the body to its configured Minecraft Java server.
Inputs: auth, host, port, version, +1 more.
minecraft_craftA
Craft an item using current inventory and a nearby crafting table when needed.
Inputs: item (required), count.
minecraft_digC
Dig the block at an exact coordinate.
Inputs: x (required), y (required), z (required).
minecraft_disconnectA
Disconnect from Minecraft.
Inputs: no named parameters.
minecraft_eatA
Eat the most nourishing recognized food in inventory.
Inputs: no named parameters.
minecraft_equipC
Equip an inventory item.
Inputs: item (required), destination.
minecraft_eventsA
Read recent world and action events after a cursor.
Inputs: limit, cursor.
minecraft_followA
Continuously follow a visible player until stopped.
Inputs: player (required), distance.
minecraft_gotoC
Walk near a world coordinate.
Inputs: x (required), y (required), z (required), range.
minecraft_inventoryB
List inventory item names, counts, and slots.
Inputs: no named parameters.
minecraft_lookA
Set absolute yaw and pitch in radians.
Inputs: yaw (required), pitch (required).
minecraft_placeC
Place an inventory block at a coordinate against a neighboring face.
Inputs: x (required), y (required), z (required), item (required), +1 more.
minecraft_sayA
Send plain Minecraft chat. Slash commands are refused.
Inputs: message (required).
minecraft_sleepA
Find and sleep in a nearby bed.
Inputs: no named parameters.
minecraft_statusA
Observe health, position, weather, gaze target, and nearby entities.
Inputs: no named parameters.
minecraft_stopA
Immediately stop navigation and held movement controls.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct action or observation, but minecraft_collect and minecraft_dig overlap somewhat in block-digging behavior. The descriptions clarify coordinate-based digging versus nearby block collection, so an agent can generally select correctly.
All tools share the consistent minecraft_ prefix and use lowercase snake_case, which is predictable. Minor deviation is that some names are nouns (status, inventory, events) rather than verbs, but this does not cause real confusion.
18 tools is slightly above the ideal range, but each tool covers a meaningful body capability like movement, inventory, combat, or world interaction. The count feels appropriate for a Minecraft agent that needs both observation and action.
The tool surface covers connection, status, movement, block manipulation, inventory, crafting, eating, sleeping, attacking, and chat. Obvious gaps include dropping items, using non-food items, and interacting with entities or containers, but core agent workflows are not blocked.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Generate AI video, images and audio, and browse your history, from any MCP client.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control a Minecraft bot for movement, building, crafting, and instant schematic-based structure spawning via MCP tools.2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Minecraft via MCP with configurable versions, creative building commands, survival helpers, and an autonomous agent loop.Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to control a Minecraft bot inside a Java Edition world via MCP, providing tools for movement, building, mining, combat, farming, trading, inventory, and world perception.551MIT
- FlicenseNot gradedqualityDmaintenanceEnables controlling an autonomous Minecraft Java Edition player through MCP, with structured world perception, navigation, gathering, crafting, combat, building, skill-based task execution, and long-term memory integration.-