Minecraft MCP Server for Claude Code: Setup & Config

What you can do with Minecraft in Claude Code

A focused Mineflayer-backed MCP bridge for hands-on assistant interaction with a Minecraft world.

• Direct an assistant-controlled character around a LAN world.
• Read and send in-game messages while interacting with the world.

Before you start: Minecraft in Claude Code

• Git
• Node.js 20.10.0 or later
• A running compatible Minecraft game with a reachable world
• An MCP-compatible client

The README opens a single-player world to LAN and configures the bot's host and port to match. Its current support notice names Minecraft 1.21.11, while the setup walkthrough mentions testing Java Edition 1.21.8. Restart the desktop client fully after configuration. No required environment variables are stated.

Minecraft Claude Code configuration

1. Choose Claude Code configuration scope

   For Minecraft MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Minecraft MCP Server to Claude Code

   Use the minecraft-mcp-server entry below in mcpServers. Keep Minecraft MCP Server's documented stdio connection fields and your other Claude Code entries.

3. Check Minecraft MCP Server in Claude Code

   Minecraft MCP Server: Inspect claude mcp list and /mcp status.

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

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

Minecraft tools available to Claude Code

Minecraft's stored tool list documents 18 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

get-position

For Minecraft's get-position, review the permission request and arguments in Claude Code before approval.

Read the bot's current coordinates.

move-to-position

For Minecraft's move-to-position, review the permission request and arguments in Claude Code before approval.

Move the bot toward specified coordinates.

look-at

For Minecraft's look-at, review the permission request and arguments in Claude Code before approval.

Aim the bot's view at a selected position.

jump

For Minecraft's jump, review the permission request and arguments in Claude Code before approval.

Make the bot perform a jump.

move-in-direction

For Minecraft's move-in-direction, review the permission request and arguments in Claude Code before approval.

Move in a chosen direction for a specified duration.

fly-to

For Minecraft's fly-to, review the permission request and arguments in Claude Code before approval.

list-inventory

For Minecraft's list-inventory, review the permission request and arguments in Claude Code before approval.

find-item

For Minecraft's find-item, review the permission request and arguments in Claude Code before approval.

equip-item

For Minecraft's equip-item, review the permission request and arguments in Claude Code before approval.

place-block

For Minecraft's place-block, review the permission request and arguments in Claude Code before approval.

dig-block

For Minecraft's dig-block, review the permission request and arguments in Claude Code before approval.

get-block-info

For Minecraft's get-block-info, review the permission request and arguments in Claude Code before approval.

find-blocks

For Minecraft's find-blocks, review the permission request and arguments in Claude Code before approval.

smelt-item

For Minecraft's smelt-item, review the permission request and arguments in Claude Code before approval.

Process items using a furnace-like block.

find-entity

For Minecraft's find-entity, review the permission request and arguments in Claude Code before approval.

Locate the closest entity matching a requested type.

send-chat

For Minecraft's send-chat, review the permission request and arguments in Claude Code before approval.

Post a message to the game's chat.

read-chat

For Minecraft's read-chat, review the permission request and arguments in Claude Code before approval.

Read recent messages sent by players.

detect-gamemode

For Minecraft's detect-gamemode, review the permission request and arguments in Claude Code before approval.

Minecraft: full stored tool descriptions

Troubleshooting Minecraft in Claude Code

• If Minecraft MCP Server fails to start, check npx (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Minecraft MCP Server uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Requires a running game and a reachable world.
• Known limitation: The compatibility notice warns that versions newer than 1.21.11 may not work.
• Known limitation: Desktop client startup can take time.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions