minecraft-mcp-server

Translates natural language commands from Claude into executable Minecraft bot actions through the Model Context Protocol. The MCP Server Core component registers all available tools as MCP resources, receives tool invocation requests from Claude Desktop, maps them to corresponding bot functions in the PositionTools, InventoryTools, BlockTools, EntityTools, ChatTools, and FlightTools modules, and returns formatted game state responses back to Claude. This creates a bidirectional bridge where Claude can understand Minecraft intent and execute complex multi-step tasks through a single natural language instruction.

Enables precise bot navigation through the Minecraft world using the PositionTools module, which wraps Mineflayer's pathfinding plugin to compute optimal routes around obstacles. The system tracks bot position in 3D coordinates (x, y, z), accepts movement commands (goto, jump, sprint, crouch), and uses the Mineflayer Pathfinder plugin to automatically navigate complex terrain including hills, water, and obstacles. Movement state is continuously reported back to Claude, allowing it to verify navigation success and adjust strategy if the bot gets stuck or encounters unexpected terrain.

Manages bot inventory state and equipment through the InventoryTools module, tracking item slots, durability, and equipped gear. The system allows Claude to equip items, drop items, craft recipes, and query inventory contents. It maintains a real-time inventory model synchronized with the Minecraft server, enabling Claude to make decisions about resource management (e.g., dropping low-durability tools, equipping armor before combat). Inventory changes are reported back to Claude with detailed item metadata including stack size, durability, and enchantments.

Enables block placement, digging, and detection through the BlockTools module, which uses Mineflayer's block interaction API to manipulate the world. Claude can place blocks at specific coordinates, dig blocks with appropriate tools, and query block properties (type, hardness, position). The system tracks block placement success and reports back the resulting world state, allowing Claude to verify structure integrity and adjust placement strategy if blocks fail to place (e.g., due to insufficient support or invalid placement rules). Block detection includes raycasting to identify blocks in the bot's line of sight.

Detects and interacts with entities (mobs, players, animals) through the EntityTools module, which queries Mineflayer's entity tracking system to identify nearby entities and their properties. Claude can find specific entity types (e.g., 'zombie', 'sheep'), get their positions and health, and interact with them (attack, feed, tame). The system maintains a real-time entity list and reports changes, allowing Claude to react to dynamic world events (e.g., hostile mobs spawning, animals appearing). Entity detection includes distance calculation and line-of-sight checks.

Enables the bot to send and receive chat messages through the ChatTools module, which interfaces with Mineflayer's chat API. Claude can send messages to other players, execute commands (if operator), and listen for incoming chat events. The system maintains a chat history and reports messages back to Claude, allowing it to respond to player requests or coordinate with other players. Chat commands are executed with proper escaping and validation to prevent injection attacks.

Enables flight control in creative mode through the FlightTools module, which uses Mineflayer's flight API to manage vertical movement and hovering. Claude can enable/disable flight, set flight speed, and navigate in three dimensions without pathfinding constraints. The system tracks flight state and altitude, allowing Claude to position the bot precisely for building or exploration tasks. Flight is particularly useful for large-scale building projects where ground-based pathfinding would be inefficient.

Provides comprehensive game state queries through the bot's state tracking system, allowing Claude to understand the current world context. This includes querying bot health, hunger, experience level, current dimension, time of day, weather, and nearby chunk status. The system maintains a real-time model of game state synchronized with the Minecraft server, enabling Claude to make context-aware decisions (e.g., seeking shelter during rain, resting when health is low). State queries are low-latency and do not require server round-trips.

Enables Claude to decompose complex Minecraft tasks into sequences of MCP tool calls with built-in error handling and recovery. The MCP Server Core manages tool invocation sequencing, captures errors from individual tool calls, and reports them back to Claude with sufficient context for recovery decisions. Claude can use this feedback to retry failed operations, adjust strategy, or skip steps based on error type. The system maintains execution context across multiple tool calls, allowing Claude to build stateful workflows (e.g., 'navigate to location, build structure, verify result, repair if needed').

Implements full Model Context Protocol compliance through the MCP Server Core, which registers all bot capabilities as typed MCP tools with JSON schema definitions. Each tool (movement, block interaction, entity detection, etc.) is exposed with input/output schemas that Claude can introspect and use for type-safe invocation. The system handles MCP protocol serialization, error marshaling, and response formatting, ensuring compatibility with any MCP-compatible client. Tool schemas include parameter descriptions, type constraints, and examples, enabling Claude to understand tool semantics without external documentation.