# minecraft-mcp-server: a Mineflayer bot that Claude drives over MCP

> Yuniko Software's TypeScript MCP server gives an LLM a Minecraft body through Mineflayer, with movement, flight, inventory, block and furnace commands. It is pinned to Minecraft 1.21.11 and expects a LAN world on localhost:25565.

**yuniko-software/minecraft-mcp-server** — 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

- Repository: https://github.com/yuniko-software/minecraft-mcp-server
- Website: https://yuniko.software/mcp-server/
- Stars: 755 · Forks: 91
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/yuniko-software-minecraft-mcp-server

## The gap minecraft-mcp-server fills between an LLM and a running world

Most LLM integrations with Minecraft stop at generating commands or datapacks that a human then pastes into the game. This project removes that step. It is an MCP server, so an MCP-compatible client such as Claude Desktop can call tools that act on a live character. The README describes the goal plainly: the bot lets assistants "build structures, explore the world, and interact with the game environment through natural language instruction."

The intended user is someone who already runs Claude Desktop and a local Java world, not a server operator managing many players. The prerequisites list Git, Node.js 20.10.0 or later, a running Minecraft game, and an MCP-compatible client. There is no hosted service and no account. The bot joins as a normal player named by the --username flag, which defaults in the README example to ClaudeBot.

If your goal is to script a bot in code, Mineflayer alone is the shorter path. The value here is the tool surface exposed to a model, which is a different problem from writing bot logic yourself.

## How the MCP tool surface maps onto Mineflayer and pathfinding

The architecture is a thin translation layer. The package depends on @modelcontextprotocol/sdk for the protocol side, mineflayer for the bot, mineflayer-pathfinder for navigation, minecraft-data for version-specific block and item information, vec3 for coordinates, yargs for CLI parsing, and zod for input validation. The compiled entry point is dist/main.js, exposed as the minecraft-mcp-server binary.

The README groups the exposed tools by intent. Movement covers get-position, move-to-position, look-at, jump and move-in-direction. Flight is a single fly-to tool. Inventory covers list-inventory, find-item and equip-item. Block work covers place-block, dig-block, get-block-info and find-blocks. There is one furnace tool, smelt-item, plus find-entity for nearby entities. Communication is send-chat and read-chat, and detect-gamemode reports the current mode.

The data flow is one-directional per call: the model picks a tool, the server validates arguments and issues a Mineflayer action, and the result returns to the conversation. The README does not describe any persistent world model or planning layer, so multi-step tasks depend on the model chaining calls. That is the design, and it is also where behavior gets uneven: a build that needs twenty coordinated placements is twenty tool calls the model has to sequence itself.

## Installing minecraft-mcp-server and getting the bot into a LAN world

There is no npm install step in the README. The configuration runs the server straight from GitHub with npx, which pulls and builds it on first launch. That means the first boot is slow, and the README warns that "it could take some time for Claude Desktop to boot the MCP server."

Start by creating a singleplayer world and opening it to LAN from the pause menu. The README states the bot tries localhost on port 25565 by default, and that both can be overridden.

Open Claude Desktop, go to File, Settings, Developer, Edit Config, and edit claude_desktop_config.json:

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": [
        "-y",
        "github:yuniko-software/minecraft-mcp-server",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "ClaudeBot"
      ]
    }
  }
}
```

Check that --host and --port match the world you opened. Then fully quit Claude Desktop, including the tray icon, and relaunch it. With the world open to LAN, the bot should join. The README notes that a prompt has to mention Minecraft explicitly, because that mention is what triggers the MCP server, and the client will ask for permission before running it.

To work on the server itself rather than just run it, the repository scripts are npm run dev for tsx src/main.ts, npm run build for tsc -p tsconfig.build.json, and npm test for ava.

## Version pinning is the sharpest constraint here

The README carries an important note: the project currently supports Minecraft version 1.21.11, and newer versions may not work. That is a hard boundary, not a soft recommendation. minecraft-data ships version-specific block and item tables, and a mismatch between those tables and the server you connect to breaks block lookups and placement.

The prerequisites section adds a second data point that sits awkwardly beside the first: the setup was tested with Minecraft 1.21.8 Java Edition from Microsoft Game Pass. So the documented test target and the documented supported version are not the same number. If you are deciding whether to adopt this, that gap is the first thing to check against your own installation before you invest time in prompts.

There is also no Bedrock path in the README. It discusses Java Edition only, and Mineflayer targets the Java protocol. A Bedrock world is out of scope regardless of version.

Finally, the tool list has no rollback or undo. The README does not document any way to revert a dig-block or place-block action, so a model that misreads coordinates changes the world and you fix it by hand.

## Where a raw Mineflayer script is the better choice

The honest alternative is Mineflayer itself, which this project depends on. The difference is where the intelligence lives. With Mineflayer directly, you write the control flow: connect a bot, call bot.pathfinder.setGoal, loop over coordinates, handle errors in your own code. Behavior is deterministic and testable, and you can run it headless without any MCP client.

With minecraft-mcp-server, the control flow moves into the model's context. You trade determinism for flexibility, because the same prompt can produce different action sequences. That is the point when you want exploratory building from an image or a vague instruction like clearing an area, and it is a liability when you need the same structure built identically every run.

A second alternative is a conventional server-side plugin or datapack. Those run inside the game with full API access and no external process, but they cannot take natural language input and they require Java plugin development rather than TypeScript. Choose based on whether the instruction source is a human typing prose or a program calling a function.

## Maintenance, licence and what upgrading actually costs

The repository is not archived and the last push was on 2026-04-04, roughly five and a half months before this writing. Recent releases are 2.0.4 on 2026-02-26, 2.0.3 on 2026-02-10 and 2.0.2 on 2026-01-30, so the release cadence in early 2026 was steady, but there is no published commit activity after April in the README and release list. Treat the project as maintained but quiet, and check the repository before depending on it.

Upgrade cost is dominated by the Minecraft version, not the server's own version. Bumping minecraft-mcp-server means re-running npx, which rebuilds from source and picks up whatever @modelcontextprotocol/sdk, mineflayer and minecraft-data resolve to at that moment. Because the config pins no version, an upgrade is implicit every time the cache is cold. Pinning a tag or commit in the npx argument would make that reproducible, though the README does not show that form.

The licence is Apache-2.0, which permits commercial and private use and requires that you keep the licence and notice files and state significant changes. It also includes a patent grant. That is the general shape of the terms; read LICENSE in the repository for the operative text rather than relying on this summary.

## Conclusion

Adopt it if you want an LLM to act inside a singleplayer Java world opened to LAN and you are comfortable pinning Minecraft to 1.21.11, because the README warns newer versions may not work. Skip it if you need Bedrock support or a stable server-side agent on a version you do not control; neither appears in the README. Before relying on it, verify the exact Minecraft build you run against the stated 1.21.11 target and confirm the host and port in claude_desktop_config.json match your LAN world.

## FAQ

### What is Minecraft MCP?

In this project it is an MCP server that exposes Minecraft actions as tools an AI assistant can call. The README describes a bot powered by large language models and the Mineflayer API that lets Claude control a Minecraft character.

### Is an MCP server a real server?

Here it is a local Node.js process that Claude Desktop launches with npx, not a remote host you connect to. It speaks the Model Context Protocol to the client and connects to your Minecraft world as a player.

### Which Minecraft version does minecraft-mcp-server support?

The README states it currently supports Minecraft version 1.21.11 and warns that newer versions may not work. The prerequisites note that the documented setup was tested with Minecraft 1.21.8 Java Edition from Microsoft Game Pass.

### How do I install minecraft-mcp-server?

There is no separate install step. You add an mcpServers entry to claude_desktop_config.json that runs npx with github:yuniko-software/minecraft-mcp-server and the --host, --port and --username arguments, then fully restart Claude Desktop.

### Does minecraft-mcp-server support Bedrock Edition?

The README only covers Java Edition, and the bot is built on Mineflayer, which targets the Java protocol. No Bedrock support is documented.

## Sources

- [License: Apache-2.0](https://github.com/yuniko-software/minecraft-mcp-server/blob/main/LICENSE)
- [Project website](https://yuniko.software/mcp-server/)
- [README](https://github.com/yuniko-software/minecraft-mcp-server/blob/main/README.md)
- [Releases](https://github.com/yuniko-software/minecraft-mcp-server/releases)
- [yuniko-software/minecraft-mcp-server on GitHub](https://github.com/yuniko-software/minecraft-mcp-server)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yuniko-software-minecraft-mcp-server