Minecraft Bot MCP server

This Minecraft MCP Server allows Claude and other language models to control a Minecraft character through the Model Context Protocol. The server bridges the gap between AI assistants and Minecraft gameplay, enabling language models to perform actions in the game world.

Prerequisites

• Git
• Node.js
• Minecraft 1.21.6 Java Edition (important: versions 1.21.7+ are not supported yet)
• An MCP-compatible client (such as Claude Desktop)

Installation and Setup

Step 1: Run Minecraft

1. Create a singleplayer world in Minecraft 1.21.6
2. Open the world to LAN (Press ESC, then select "Open to LAN")
3. Note the port number shown after opening to LAN (the default is 25565)

Step 2: Configure Claude Desktop

1. Install Claude Desktop if you haven't already
2. Open Claude Desktop
3. Navigate to File → Settings → Developer → Edit Config
4. Locate the claude_desktop_config.json file
5. Insert the following configuration:

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

6. Adjust the --port and --host parameters if needed to match your Minecraft LAN settings
7. Completely restart Claude Desktop (make sure to close it in your system tray)

Using the MCP Server

Starting the Connection

1. Make sure your Minecraft world is running and open to LAN
2. Launch Claude Desktop
3. The MCP server will automatically start, and the bot should join your Minecraft world
4. You'll see a confirmation in Claude Desktop when the server has successfully booted

Interacting with the Bot

To control the Minecraft character using Claude:

1. Start a chat in Claude Desktop
2. Mention that you want Claude to perform actions in Minecraft
3. Claude will ask for permission to use the MCP server
4. After granting permission, you can give commands to the bot

For example, you can:

• Ask Claude to build structures (you can even upload images of buildings)
• Direct the bot to gather resources
• Have the bot explore the world
• Request the bot to craft items

Available Commands

The MCP server supports various commands that Claude can use to control the Minecraft character:

Movement Commands

• get-position - Retrieve current coordinates
• move-to-position - Navigate to specific coordinates
• look-at - Direct the bot's gaze
• jump - Make the bot jump
• move-in-direction - Move in a specified direction for a set duration
• fly-to - Fly directly to coordinates

Inventory Management

• list-inventory - Show all inventory items
• find-item - Locate a specific item
• equip-item - Equip an item to hand or armor slot

Block Interaction

• place-block - Place a block at coordinates
• dig-block - Mine a block at coordinates
• get-block-info - Get information about a block
• find-block - Locate the nearest block of a specific type

Entity Interaction

• find-entity - Find the nearest entity of a specific type

Communication

• send-chat - Send in-game messages
• read-chat - View recent player messages

Game State

• detect-gamemode - Identify the current game mode

For practical examples of the bot in action, you can view this shared Claude chat.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect