About mc-mcp-server
mc-mcp-server is a Java MCP server that connects a bot to a Minecraft Java Edition 1.21.7 server as an offline player. It provides tools for movement, inventory, block and entity inspection, chat, and construction tasks.
Key features
- 01Join a Minecraft server as a bot
- 02Navigate and move through the world
- 03Inspect inventory, blocks, and entities
- 04Place, dig, fill, and clear blocks
- 05Chat and send server commands
Use cases
- 01Move a bot to a target position
- 02Build structures from a list of blocks
- 03Scan terrain before planning construction
- 04Inspect inventory or nearby entities
MCP support
The server exposes Minecraft bot actions and world information as MCP tools, including movement, inspection, building, and chat.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
We haven’t collected a package or remote endpoint for this server. Follow the instructions in the project README.
Tools
Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.
Details
From the project README
mc-mcp-server
claude opus5.5 build the castle
⛏️ Model Context Protocol server for Minecraft.
Install
Usage
the bot joins a minecraft java edition 1.21.7 server as an offline player,
so the server needs online-mode=false. op the bot (/op LLMBot) if you want it to run commands.
java -cp ... vavi.games.minecraft.mcp.MinecraftBotMCP [-host localhost] [-port 25565] [-username LLMBot]
tools
| name | description |
|---|---|
| get-position | position, game mode and health |
| move-to-position | walks to a position with path finding (walk, step up, drop down) |
| look-at | turns the head to a position |
| jump | jumps |
| move-in-direction | walks forward/back/left/right for a duration |
| list-inventory, find-item | inventory contents |
| equip-item | moves an item to the hand, off-hand or an armor slot |
| place-block | places the held block (walks within reach if needed) |
| dig-block | digs a block, takes the vanilla breaking time in survival |
| get-block-info, find-block | reads the bot's copy of the loaded chunks |
| find-entity | the nearest entity by type or player name |
| send-chat | chat, or a command when it starts with /; returns the server's response messages |
| build-blocks | places a list of blocks in one call: equips items, orders placements so each block has support, walks within reach, builds temporary pillars for high positions, resumable |
| fill-region | fills a box (solid, hollow or walls) the same way |
| clear-region | digs a box from the top (optionally only matching blocks, e.g. logs), with the best tool in the inventory |
| scan-area | height map of an area (optionally ignoring trees) for planning |
the bot walks through leaves by digging them, and picks the best tool (axe, pickaxe, shovel, hoe) for digging.
game data
src/main/resources/vavi/games/minecraft/mcp/{blocks.tsv,items.txt} are generated from the vanilla server's data reports
(java -DbundlerMainClass=net.minecraft.data.Main -jar server.jar --reports)
and minecraft-data's block collision shapes.
regenerate them when mcprotocollib's protocol version changes.
References
- https://github.com/GeyserMC/MCProtocolLib
- https://github.com/modelcontextprotocol/java-sdk
- https://github.com/yuniko-software/minecraft-mcp-server
TODO
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.