minecraft-mcp-server: giving Claude hands inside a Minecraft world
A Minecraft MCP Server powered by Mineflayer API. It allows to control a Minecraft character in real-time, allowing AI assistants to build structures, explore the world, and interact with the game environment through natural language instruction
At a glance
- What is it?
- The yuniko-software MCP server wraps Mineflayer in a Model Context Protocol tool surface so a chat client can move, dig, place blocks and smelt. It is a single-version, LAN-only bridge, and the version pin is the first thing to check before you install it.
- Who is it for?
- Adopt it if you want a local, single-player sandbox where a Claude Desktop chat drives one bot and you accept that the README pins support to Minecraft 1.21.11. Do not adopt it if you need a bot on a public server, a version outside that pin, or unattended operation without a chat client in the loop.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 164 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the MCP layer buys you over scripting Mineflayer yourself
Mineflayer already lets you script a Minecraft bot in JavaScript. What it does not give you is a way for a language model to decide what the bot does next. This project supplies that middle layer. It is an MCP server, so the bot's capabilities are published as named tools that an MCP-compatible client can call. The README frames the goal plainly: the bot uses the Model Context Protocol to let Claude and other supported models control a Minecraft character.
The intended user is someone who already has Claude Desktop installed and wants to watch a model act inside a world rather than describe one. The README suggests giving the bot commands through any active Claude Desktop chat and notes you can upload images of buildings and ask the bot to build them. That is the whole pitch: natural language in, block placement out. It is not a framework for building a game agent, and the README does not present it as one.
The tool surface is the architecture
There is no elaborate pipeline here. The MCP client sends a tool call, the server translates it into a Mineflayer action, and the result goes back as the tool response. What matters for evaluation is the shape of that surface, because it defines what a model can and cannot express.
The README groups the commands into seven areas. Movement covers get-position, move-to-position, look-at, jump and move-in-direction. Flight has a single entry, fly-to, described as making the bot fly directly to specific coordinates. Inventory work goes through list-inventory, find-item and equip-item. Block interaction is the largest group: place-block, dig-block, get-block-info and find-blocks. There is one furnace command, smelt-item, described as smelting items using a furnace-like block. Entity interaction is a single find-entity call for the nearest entity of a given type. Communication covers send-chat and read-chat. Game state has detect-gamemode.
Read that list as a statement of scope. There is no crafting tool, no container or chest transfer, no combat or attack command, no follow-entity, no pathfinding to a named location, and no sleep or respawn handling. A model can locate an entity but the README lists no way to act on it. It can smelt but not craft. If your intended task needs any of those, the tool surface will stop you before the model's reasoning does.
Setup is a config file and a LAN world
The prerequisites are Git, Node.js 20.10.0 or newer, a running Minecraft game, and an MCP-compatible client. The README uses Claude Desktop as its example and notes other MCP clients are supported.
On the game side you create a singleplayer world and open it to LAN through ESC then Open to LAN. The bot tries localhost on port 25565 by default, and the README says both values can be overridden in the client config.
On the client side you open File, Settings, Developer, Edit Config in Claude Desktop, find claude_desktop_config.json, and add a server entry. The README's example uses npx with the GitHub repository spec directly:
{ "mcpServers": { "minecraft": { "command": "npx", "args": [ "-y", "github:yuniko-software/minecraft-mcp-server", "--host", "localhost", "--port", "25565", "--username", "ClaudeBot" ] } } }
So the three flags the server accepts are --host, --port and --username. The README warns to double-check those host and port values and to fully restart Claude Desktop, including from the OS tray. It also warns that booting the MCP server can take some time, and that you should mention Minecraft in your prompt because that mention is what triggers the server to run and ask for permissions.
The version pin is the constraint that will bite first
The README carries an important note near the top: the project currently supports Minecraft version 1.21.11, newer versions may not work, and support will be added as soon as possible. The prerequisites section then says the setup was tested with Minecraft 1.21.8 Java Edition included in Microsoft Game Pass.
Those two statements sit next to each other and do not agree on a number. The support note names 1.21.11 and the testing note names 1.21.8. Both are in the README as written. If you are choosing a world to point this at, that discrepancy is worth resolving yourself rather than assuming either figure is the operative one. Mineflayer's protocol support is version-sensitive, so a mismatch between the client version and the server's expectations is the most likely source of a connection that opens and then behaves oddly.
The second constraint is the LAN requirement. The documented path is a singleplayer world opened to LAN, with the bot joining localhost on 25565. Nothing in the README describes connecting to a remote or public server, handling authentication for an online-mode server, or running more than one bot. Treat the documented setup as the supported one.
Where a scripted bot or a different MCP server fits better
The honest alternative for a fixed task is plain Mineflayer. If you know the sequence (walk to these coordinates, dig this block type, place that block), writing it as a Node script removes the model from the loop entirely. It runs the same way every time, costs nothing per action, and does not depend on a chat client being open. The trade-off is that it cannot react to something it was not written for, which is exactly the case this project exists to cover.
If you want model-driven control but not Minecraft, the same MCP pattern appears in other servers that expose file system or shell tools. Those give a model access to your machine rather than a game world. The difference in approach is the risk profile: a bot that misplaces a block in a throwaway world is cheap, while a tool that writes to your filesystem is not. That is an argument for keeping this project pointed at a disposable world, which is also what the LAN setup implies.
Within Minecraft specifically, the README does not name or compare against any other bot-control project, so there is no basis here for ranking it against one.
Maintenance, releases and what Apache-2.0 means here
The repository is TypeScript, licensed Apache-2.0, and not archived. The recent release list shows 2.0.4 on 2026-02-26, preceded by 2.0.3 on 2026-02-10 and 2.0.2 on 2026-01-30. Three releases inside roughly one month suggests active work on the 2.0 line at that time, though the README does not describe what changed between them.
The larger maintenance cost is not in this repository. It is the Minecraft version treadmill. The README's own support note says newer game versions may not work and that support will be added as soon as possible. That means a Minecraft update can leave you waiting on a change here, and the client config installs straight from the GitHub repository spec rather than a pinned version, so a fresh npx run pulls whatever is on the default branch at that moment. If you need reproducibility, pinning to a specific release is the safer habit, though the README does not document how to do that with the npx form it shows.
On licensing: Apache-2.0 permits commercial use and modification and includes an explicit patent grant, with the usual requirements around preserving notices and stating changes. That is a general description of the licence, not legal advice. The README itself adds no extra terms or usage restrictions.
Who should install this, and what to check in the first ten minutes
Install it if you want to watch a model operate inside Minecraft and you are comfortable with a disposable singleplayer world. The setup is short, the tool list is readable in a couple of minutes, and the failure mode of a wrong block placement is a wrong block placement.
Skip it if you need a bot on a server you care about, if your game version is outside the range the README discusses, or if you want the bot to run without a chat client open. The README describes no headless mode and no scheduling.
What to verify first: match your Minecraft version against the README's support note before you touch the config, since the note and the testing paragraph disagree. Then confirm the world is open to LAN and that the --host and --port values in claude_desktop_config.json match it, and restart Claude Desktop fully rather than closing the window. Finally, walk the tool list against your intended task. If the action you want is not among the twenty or so commands the README lists, no amount of prompt phrasing will produce it.
Editorial conclusion
Adopt it if you want a local, single-player sandbox where a Claude Desktop chat drives one bot and you accept that the README pins support to Minecraft 1.21.11. Do not adopt it if you need a bot on a public server, a version outside that pin, or unattended operation without a chat client in the loop. Before installing, confirm your game version matches the README note, confirm the world is opened to LAN on the host and port you put in claude_desktop_config.json, and check whether the tool list covers the action you actually need.
Community notes