Minecraft Survival MCP Server

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