minecraft-mcp-server

minecraft-mcp-server

An MCP (Model Context Protocol) server that connects an AI assistant to a Minecraft server via a Mineflayer bot. Supports creative and survival modes with distinct toolsets for each. The bot auto-connects on startup using config from environment variables — no connection parameters are passed from the agent.

Communicates over stdio — plug it into any MCP-compatible client (Claude Desktop, etc.).

Prerequisites

• Node.js ≥ 20
• Minecraft Java Edition server (vanilla, Paper, Spigot, etc.)
• Server must be in offline mode (online-mode=false in server.properties) or configured for the bot to join without auth
• Creative mode: bot needs operator permissions (/op <username>) for command tools (setblock, fill, etc.)
• Survival mode: no special server permissions required

Quick Start

npm install
npm run build

Scripts

| Script | Command | Description | |--------|---------|-------------| | build | tsc -p tsconfig.json | Compile TypeScript to dist/ | | dev | tsx src/main.ts | Run directly without compiling | | start | node dist/main.js | Run compiled output |

Configuration

All configuration is via environment variables. The bot connects automatically on startup — the agent never passes connection parameters.

| Variable | Default | Description | |----------|---------|-------------| | MC_MODE | creative | Mode: creative or survival. Determines which tools are exposed. | | MC_HOST | 127.0.0.1 | Minecraft server host. | | MC_PORT | 25565 | Minecraft server port. | | MC_USERNAME | mcp-bot | Bot username. | | MC_VERSION | (auto-detect) | Minecraft protocol version (e.g. 1.20.4). | | MC_AUTO_CONNECT | true | Connect to the server on startup. Set to false to defer connection. |

MCP Client Integration

This server uses stdio transport. Set the mode and connection via env in your MCP client config.

Creative mode (default)

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/absolute/path/to/dist/main.js"],
      "env": {
        "MC_MODE": "creative",
        "MC_HOST": "localhost",
        "MC_PORT": "25565",
        "MC_USERNAME": "Builder"
      }
    }
  }
}

Survival mode

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/absolute/path/to/dist/main.js"],
      "env": {
        "MC_MODE": "survival",
        "MC_HOST": "localhost",
        "MC_PORT": "25565",
        "MC_USERNAME": "Survivor"
      }
    }
  }
}

Development (no build step)

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/src/main.ts"],
      "env": {
        "MC_MODE": "survival"
      }
    }
  }
}

Tools

Tools are split into common (always available), creative-only, and survival-only sets depending on the configured MC_MODE.

Common Tools (both modes)

| Tool | Description | |------|-------------| | reconnect_bot | Reconnect to the configured Minecraft server | | get_bot_status | Get state, position, health, food, recent chat | | send_chat | Send a chat message in-game | | get_position | Get current coordinates and orientation | | look_at | Look at specific world coordinates | | move_control | Set movement state (forward/back/left/right/jump/sprint/sneak) with optional auto-stop duration | | stop_all_controls | Stop all movement | | get_inventory | List inventory items |

Creative-Only Tools

Available when MC_MODE=creative. These use server commands and require operator permissions.

| Tool | Description | |------|-------------| | setblock | Place a block at coordinates — modes: replace, destroy, keep | | fill | Fill a cuboid region — modes: replace, destroy, keep, hollow, outline | | clone_area | Clone a cuboid region to a destination | | give_item | Give an item to a player (default: the bot) | | teleport_to | Teleport the bot to coordinates with optional rotation | | set_time | Set world time (day, noon, night, or tick value) | | set_weather | Set weather (clear, rain, thunder) with optional duration | | set_gamerule | Set a game rule | | summon_entity | Summon an entity with optional NBT data | | fly_to | Fly the bot to coordinates using creative flight (fallback chain: direct → arc → teleport) |

Survival-Only Tools

Available when MC_MODE=survival. These use Mineflayer plugins (pathfinder, collectblock, tool) for autonomous bot behavior — no operator permissions needed.

| Tool | Description | |------|-------------| | go_to | Navigate to coordinates using pathfinding (handles obstacles automatically) | | dig_block | Mine a block at coordinates (auto-equips best tool) | | place_block | Place a block from inventory at coordinates | | collect_block | Find, navigate to, mine, and collect blocks of a type | | craft_item | Craft an item using inventory materials (auto-finds crafting table if needed) | | equip_item | Equip an item to a slot (hand, head, torso, legs, feet, off-hand) |

Why no execute_command? We intentionally expose explicit, typed tools instead of a raw command passthrough. Each tool validates its inputs and returns structured results, giving the agent better feedback and preventing command-injection mistakes.

Structured Tool Output

All creative command tools (setblock, fill, clone_area, give_item, teleport_to, set_time, set_weather, set_gamerule, summon_entity) return structured metadata alongside the human-readable text:

| Field | Type | Description | |-------|------|-------------| | executed | boolean | Whether the command was confirmed as successfully executed | | category | string | Outcome category: success, permission_denied, unknown_command, failed, or timeout | | timedOut | boolean | Whether the server feedback window expired before a response was received |

Unconfirmed, timed-out, and failed outcomes are reported as errors (isError: true) so the agent can detect and recover from issues automatically.

fly_to uses a three-stage fallback chain and returns additional fields:

| Field | Type | Description | |-------|------|-------------| | method | string | Which strategy succeeded: direct_fly, arc_fly, or teleport_fallback | | executionConfirmed | boolean | Whether the bot arrived at the target coordinates | | arrivedAt | object \| null | Final {x, y, z} position after the attempt |

Examples

Creative mode

# Fly to a build site
fly_to(x: 100, y: 80, z: 200)

# Place a single diamond block
setblock(x: 100, y: 64, z: 200, block: "diamond_block")

# Build a 10×1×10 stone platform
fill(x1: 0, y1: 63, z1: 0, x2: 10, y2: 63, z2: 10, block: "stone")

# Hollow out a cube of glass
fill(x1: 0, y1: 64, z1: 0, x2: 10, y2: 74, z2: 10, block: "glass", mode: "hollow")

# Give yourself 64 diamonds
give_item(item: "diamond", count: 64)

# Set daytime
set_time(value: "day")

Survival mode

# Navigate to coordinates
go_to(x: 100, y: 64, z: 200)

# Mine a block (auto-selects best tool)
dig_block(x: 100, y: 63, z: 200)

# Collect 10 oak logs nearby
collect_block(blockName: "oak_log", count: 10)

# Craft planks from logs
craft_item(itemName: "oak_planks", count: 4)

# Equip a sword
equip_item(itemName: "stone_sword", destination: "hand")

Troubleshooting

Permission denied (creative mode)

The bot needs operator permissions on the server:

/op <bot_username>

Creative command tools (setblock, fill, etc.) return isError: true with category "permission_denied" if the bot lacks permissions.

Unknown command

Returned when a command is invalid or misspelled. Check:

• Correct block IDs (e.g. stone, diamond_block, not Stone)
• Valid coordinate ranges
• Proper command syntax

No response / timeout

Creative command tools wait 5 seconds for server feedback. A timeout means:

• The command may have executed but produced no recognizable response
• The server may be lagging

The tool returns category: "timeout" and timedOut: true, and is treated as an error (isError: true) so the agent can decide how to proceed.

fly_to failures

fly_to automatically tries three strategies in order:

1. Direct flight — bot.creative.flyTo() to the target
2. Arc flight — rises to a dynamic altitude above current/target Y, flies horizontally, then descends (avoids obstacles)
3. Teleport fallback — /tp command if both flight methods fail

Check method in the response to see which strategy was used. If all three fail, executionConfirmed is false and isError is true.

Connection issues

• Verify the Minecraft server is running and reachable
• Check online-mode=false in server.properties for offline-mode bots
• Ensure the port is correct (default: 25565)
• The bot cannot connect if the server is full or the username is already in use
• Check MC_AUTO_CONNECT is not set to false if you expect auto-connection