Minecraft MCP Server
A Minecraft bot powered by large language models and [Mineflayer API](https://github.com/PrismarineJS/mineflayer). This bot uses the [Model Context Protocol](https://github.com/modelcontextprotocol) (MCP) to enable Claude and other supported models to control a Minecraft character.
## Prerequisites
- Git
- Node.js
- A running Minecraft game (the setup below was tested with Minecraft 1.21.4 Java Edition included in Microsoft Game Pass)
- An MCP-compatible client. Claude Desktop will be used as an example, but other MCP clients are also supported
## Getting started
This bot is designed to be used with Claude Desktop through the Model Context Protocol (MCP).
### Run Minecraft
Create a singleplayer world and open it to LAN (`ESC -> Open to LAN`). Bot will try to connect using port `25565` and hostname `localhost`. These parameters could be configured in `claude_desktop_config.json` on a next step.
### MCP Configuration
Make sure that [Claude Desktop](https://claude.ai/download) is installed. Open `File -> Settings -> Developer -> Edit Config`. It should open installation directory. Find file with a name `claude_desktop_config.json` and insert the following code:
```json
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": [
"-y",
"github:yuniko-software/minecraft-mcp-server",
"--host",
"localhost",
"--port",
"25565",
"--username",
"ClaudeBot"
]
}
}
}
```
Double-check that right `--port` and `--host` parameters were used. Make sure to completely reboot the Claude Desktop application (should be closed in OS tray).
## Running
Make sure Minecraft game is running and the world is opened to LAN. Then start Claude Desktop application and the bot should join the game.
It could take some time for Claude Desktop to boot the MCP server. The marker that the server has booted successfully:
You can give bot any commands through any active Claude Desktop chat. You can also upload images of buildings and ask bot to build them 😁
Don't forget to mention that bot should do something in Minecraft in your prompt. Because saying this is a trigger to run MCP server. It will ask for your permissions.
## Available Commands
Once connected to a Minecraft server, Claude can use these commands:
### Movement
- `get-position` - Get the current position of the bot
- `move-to-position` - Move to specific coordinates
- `look-at` - Make the bot look at specific coordinates
- `jump` - Make the bot jump
- `move-in-direction` - Move in a specific direction for a duration
### Flight
- `fly-to` - Make the bot fly directly to specific coordinates
### Inventory
- `list-inventory` - List all items in the bot's inventory
- `find-item` - Find a specific item in inventory
- `equip-item` - Equip a specific item
### Block Interaction
- `place-block` - Place a block at specified coordinates
- `dig-block` - Dig a block at specified coordinates
- `get-block-info` - Get information about a block
- `find-block` - Find the nearest block of a specific type
### Entity Interaction
- `find-entity` - Find the nearest entity of a specific type
### Communication
- `send-chat` - Send a chat message in-game
### Game State
- `detect-gamemode` - Detect the gamemode on game
TDQS
Scored across 16 tools
Each tool has a clearly distinct purpose targeting specific Minecraft actions like movement (fly-to, move-to-position), interaction (dig-block, place-block), information retrieval (get-block-info, list-inventory), or entity management (find-entity, find-item). There is no significant overlap that would cause confusion between tools.
Most tools follow a consistent verb-noun pattern (e.g., dig-block, equip-item, find-block) with clear actions. However, there are minor deviations like 'detect-gamemode' (verb-noun) and 'get-position' (verb-noun) which slightly break the pattern, but overall naming is highly readable and predictable.
With 16 tools, the count is on the higher side but reasonable for a Minecraft bot server covering movement, inventory, block interaction, and entity management. It feels slightly heavy but each tool appears to earn its place without obvious redundancy.
The tool set covers core Minecraft bot operations well, including movement (fly-to, move-to-position), block handling (dig-block, place-block, get-block-info), inventory management (list-inventory, find-item), and entity interaction (find-entity). Minor gaps might include actions like attacking entities or crafting, but the surface is largely complete for basic bot functionality.