Minecraft Survival MCP Server

A TypeScript Model Context Protocol (MCP) server for Minecraft Survival, powered by Mineflayer. This server is specifically designed to allow LLM agents to play and survive in Minecraft.

Vision: The Helix Approach

This project is inspired by the architecture of Figure AI’s Helix. While existing implementations like yuniko-software/minecraft-mcp-server provide a comprehensive set of low-level tools, mc-mcp is designed to shift the burden of "trivial" execution away from the LLM.

The Mind (LLM): Focuses on high-level intent, strategy, and long-term goals.
The Body (MCP Server): Handles the "transactions"—autonomous pathfinding, geometric math, block-by-block construction logic, and environmental processing.

The goal is to prevent the LLM from getting bogged down in coordinate arithmetic or individual tool selection, allowing it to act as a pure cognitive layer.

Quick Start

Installation

npm install
npm run build

Screenshot Dependency (Optional)

The capture_bot_view tool needs node-canvas-webgl.

Use Node 24 LTS (or 22 LTS) before installing:

nvm install 24
nvm use 24
npm install github:PrismarineJS/node-canvas-webgl

The Helix Approach & Key Improvements

Traditional Minecraft MCP implementations often treat the LLM as a "low-level controller." This results in high latency, token waste, and frequent failures due to the LLM struggling with 3D coordinate math or step-by-step block placement.

mc-mcp flips this model by implementing a "Transactional Body" architecture:

1. Intent vs. Execution (Mind/Body Split)

Instead of asking the LLM to "Move forward, then turn left, then jump," the LLM simply states "Go to the village at [X, Y, Z]." The MCP server (the Body) handles the A* pathfinding, obstacle avoidance, and physics calculations autonomously.

2. Transactional Operations

Complex tasks are exposed as single high-level transactions.

Current: get_own_position, move_to_coordinates, move_to_player, open_door_or_trapdoor, close_door_or_trapdoor, mine_block_by_coords, mine_room, break_tree, mine_stairs, place_block_at, place_wall, place_ceiling, get_inventory_contents, get_inventory_status, drop_inventory_item, put_item_in_chest, take_item_from_chest, get_chest_contents, get_chest_status, craft_item, smelt_item, capture_bot_view, get_biome_info, get_daytime_info, sleep_in_bed, locate_blocks_in_area, locate_dropped_items, search_blocks_wiki, search_items_wiki, get_crafting_recipe, list_players, find_player, get_player_coordinates, distance_to_player, find_nearest_players.
Planned: build_structure (Geometric templates handled by the server), harvest_area (Area scanning and path optimization).

3. Reduced Cognitive Load

By abstracting the "how," the LLM has more context window available for the "why"—allowing for more complex reasoning, multi-agent coordination, and creative problem-solving without being distracted by Minecraft's technical constraints.

4. Container-First Architecture

Designed to run in isolated environments (Docker/GHCR), making it easy to deploy "worker bees" that can be controlled by a centralized intelligence.

Development & Deployment

Local Development

npm install
npm run dev

Environment Variables

MCP_TRANSPORT: Set to remote to enable the HTTP/SSE server (default: stdio).
PORT: Port for the remote server (default: 3000).
HOST: Host for the remote server (default: 0.0.0.0).
MC_HOST: Minecraft server host used at startup (default: localhost).
MC_PORT: Minecraft server port (default: 25565).
MC_USERNAME: Bot username (default: MCP-Bot).
ENABLE_VIEWER: Set to 1/true to start prismarine-viewer web stream after bot spawn (default: disabled). Viewer page includes a HUD overlay (hearts and held item).
VIEWER_PORT: Port for prismarine-viewer (default: 3000).
ENABLE_IMAGES: Set to 1/true to enable registration of capture_bot_view.
LOG_LEVEL: Pino log level (trace, debug, info, warn, error, fatal; default: info).

Available Tools

Movement Module

get_own_position: Get the bot's current coordinates.
move_to_coordinates: Move to target coordinates. Inputs: x, y, z, allow_block_breaking, allow_block_placement, timeout_ms.
move_to_player: Move near a player. Inputs: username, range, allow_block_breaking, allow_block_placement, timeout_ms.
open_door_or_trapdoor: Open a door/trapdoor by optional coordinates or nearest in range. Inputs: optional x, y, z, max_distance.
close_door_or_trapdoor: Close a door/trapdoor by optional coordinates or nearest in range. Inputs: optional x, y, z, max_distance.

Mining Module

mine_block_by_coords: Mine one block with mineability/tool checks. Inputs: x, y, z, timeout_ms.
mine_room: Mine a cuboid area layer-by-layer. Inputs: start_x, start_y, start_z, length, width, depth, timeout_ms.
break_tree: Break all connected log-like blocks (log, stem, hyphae). Inputs: x, y, z, timeout_ms, allow_build_up_if_needed.
mine_stairs: Create a descending stair tunnel to a target depth. Inputs: depth, timeout_ms.

Building Module

place_block_at: Place one block at coordinates with support/entity/inventory checks. Inputs: block_name, x, y, z, timeout_ms.
place_wall: Place a wall plane from start coordinates. Inputs: block_name, start_x, start_y, start_z, x_length, y_height, z_length, optional x_direction, y_direction, z_direction, timeout_ms. Resource check is enforced before building.
place_ceiling: Place a ceiling plane from start coordinates. Inputs: block_name, start_x, start_y, start_z, x_length, z_length, optional x_direction, z_direction, timeout_ms. Resource check is enforced before building.

Inventory Module

get_inventory_contents: List inventory item stacks with item names and counts.
get_inventory_status: Report inventory slot usage (used, free, total).
drop_inventory_item: Drop items by query/name and amount. Inputs: query, count. Returns clear errors if missing or insufficient quantity.
put_item_in_chest: Put items from inventory into the nearest chest in reach. Inputs: query, count. Returns clear errors if chest/item is missing.
take_item_from_chest: Take items from the nearest chest in reach into inventory. Inputs: query, count. Returns clear errors if chest/item is missing or insufficient.
get_chest_contents: List nearest chest contents with item names and counts.
get_chest_status: Report nearest chest slot usage (used, free, total).

Vision Module

capture_bot_view: Capture a first-person screenshot from the bot. Inputs: width (default 800), height (default 400), view_distance in blocks (default 96), quality, look_at_x, look_at_y, look_at_z.
get_biome_info: Get biome info at current or optional coordinates. Inputs: optional x, y, z.
get_daytime_info: Get day/time state and ticks until sleep window.
sleep_in_bed: Sleep in bed by optional coordinates or nearest bed in range. Inputs: optional x, y, z, max_distance, timeout_ms.
locate_blocks_in_area: Locate blocks by name/id/wildcard, sorted by nearest. Inputs: query, radius, max_results, optional center_x, center_y, center_z.
locate_dropped_items: Locate dropped item entities, sorted by nearest. Inputs: radius, max_results, optional query.

Wiki Module

search_blocks_wiki: Search block names and ids from Mineflayer's built-in registry. Inputs: query, max_results.
search_items_wiki: Search item names and ids from Mineflayer's built-in registry. Inputs: query, max_results.
get_crafting_recipe: Show recipe ingredient requirements for an item and amount, including crafting-table requirement. Inputs: item, amount.

Crafting Module

craft_item: Craft an item by name and amount. Uses inventory crafting or a nearby crafting table. On failure, returns actionable guidance about missing resources and/or crafting table requirement. Inputs: item, amount.
smelt_item: Smelt an item in a nearby furnace-like block. On failure, returns actionable guidance about missing furnace, fuel, and/or input resources. Inputs: item, amount, optional fuel_query. Uses a fixed internal timeout (2x the normal Minecraft smelt time) for progress stalls.

Multiplayer Module

list_players: Get all currently known players on the server.
find_player: Search players by partial username (case-insensitive). Inputs: query.
get_player_coordinates: Get coordinates of a visible player. Inputs: username.
distance_to_player: Calculate 3D distance from the bot to a player in blocks. Inputs: username.
find_nearest_players: Find nearest visible players. Inputs: x_parameter.

The server manages exactly one bot process and attempts connection automatically on startup.

License

MIT

Minecraft Survival MCP Server