mcp-minecraft

# Minecraft MCP Integration A Model Context Protocol (MCP) integration for Minecraft that enables AI assistants to interact with a Minecraft server. This integration allows AI models to observe and interact with the Minecraft world through a bot.  ## Prerequisites 1. Minecraft Launcher 2. Node.js 18 or higher 3. Claude Desktop App 4. Java 21.0.5 (recommended) > ⚠️ Note: Currently only tested on macOS/Linux. Windows compatibility is not guaranteed. ## Important Note 1. **Use the F3+P Shortcut**: Press F3 + P together. This toggles the "Pause on Lost Focus" feature. Once turned off, you can switch to claude desktop and Minecraft will continue running without pausing.  2. **Connection Issues on Claude Restart**: If you restart Claude while the Minecraft server is running, you may experience MCP connection issues on the next claude launch due to lingering java process. See [Troubleshooting: MCP Connection Failed](#common-issues) for resolution steps. ## Installation Steps 1. **Download and Setup Minecraft Server** - Download Minecraft server v1.21 from [mcversions.net/1.21](https://mcversions.net/download/1.21) - Install Java 21.0.5 if not already installed (other versions are untested) - Create a dedicated directory (e.g., `~/minecraft-server/`) - Place the downloaded `server.jar` file in this directory - Note down the absolute path to your `server.jar` file 2. **Install and Configure MCP Integration** Quick Install (Recommended): ```bash npx -y @smithery/cli install mcp-minecraft --client claude ``` Follow the CLI prompts to complete the setup. Or Manual Setup: - Navigate to `~/Library/Application Support/Claude/claude_desktop_config.json` - Add the MCP server configuration: ```json { "mcpServers": { "mcp-minecraft": { "command": "npx", "args": [ "-y", "mcp-minecraft@latest", "--server-jar", "/absolute/path/to/minecraft-server/server.jar" ] } } } ``` > ⚠️ Replace `/absolute/path/to/minecraft-server/server.jar` with your actual server.jar path 4. **Launch Claude Desktop** - Start Claude Desktop after completing the configuration 5. **Connect to Server** - Open Minecraft Launcher - Install and launch Minecraft Java Edition **v1.21** - Click "Play" and Select "Multiplayer" - Click "Add Server" - Enter server details: - Server Name: `Minecraft Server` - Server Address: `localhost:25565` - Click "Done" ## Features ### Resources The integration exposes these MCP resources: - `minecraft://bot/location` - Current bot position in the world - `minecraft://bot/status` - Bot connection status ### Tools Available MCP tools: - `chat` - Send chat messages to the server - `jump` - Make the bot jump - `moveForward` - Make the bot move forward - `moveBack` - Make the bot move backward - `turnLeft` - Make the bot turn left - `turnRight` - Make the bot turn right - `placeBlock` - Place a block at specified coordinates - `digBlock` - Break a block at specified coordinates - `getBlockInfo` - Get information about a block at specified coordinates - `selectSlot` - Select a hotbar slot (0-8) - `getInventory` - Get contents of bot's inventory - `equipItem` - Equip an item by name to specified destination - `getStatus` - Get bot's current status (health, food, position, etc.) - `getNearbyEntities` - Get list of nearby entities within range - `attack` - Attack a nearby entity by name - `useItem` - Use/activate the currently held item - `stopUsingItem` - Stop using/deactivate the current item - `lookAt` - Make the bot look at specific coordinates - `followPlayer` - Follow a specific player - `stopFollowing` - Stop following current target - `goToPosition` - Navigate to specific coordinates ## Technical Details - Server runs in offline mode for local development - Default memory allocation: 2GB - Default port: 25565 - Bot username: MCPBot ## Troubleshooting ### Common Issues 1. **MCP Connection Failed** - Look for lingering Java processes - Terminate them manually: - Windows: Use Task Manager (untested) - Mac/Linux: - Go to 'Activity Monitor' and 'Force Quit' java - Restart computer if process termination fails - Note: Latest version should auto-resolve these issues 2. **Server Won't Start** - Verify Java is installed - Check server.jar path is correct - Ensure port 25565 is available 3. **Can't Connect to Server** - Verify server is running (check logs) - Confirm you're using "localhost" as server address - Check firewall settings ### Logs Location - Minecraft Server logs: Check the minecraft-server directory - Claude Desktop logs: `~/Library/Logs/Claude/mcp*.log` ## Contributing Contributions, big or small, are welcome! ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.