MCP Server mod

# 🤖 MCP Server Mod **Transform your Minecraft experience by connecting AI assistants directly to your game!** MCP Server Mod implements the **Model Context Protocol (MCP)** standard, creating a **streamable HTTP server** that allows Large Language Models like Claude, GPT, and other AI assistants to interact with your Minecraft world through structured commands. ## ✨ What This Mod Does This mod runs a **streamable HTTP server on port 8080** that accepts MCP protocol requests, enabling AI assistants to: - 🏗️ **Build structures** by executing placement commands - 🔍 **Analyze your world** by scanning block areas - 📊 **Get player information** including position, health, and inventory - 🎮 **Control game mechanics** through safe command execution ## 🛠️ Available Tools ### 1. execute_commands - Command Execution Execute Minecraft commands with comprehensive safety validation: - **Supported commands**: `fill`, `setblock`, `clone`, `summon`, `tp`, `give`, `gamemode`, `effect`, `enchant`, `weather`, `time`, `say` - **Safety limits**: Prevents destructive operations like mass entity killing or excessive area modifications - **Result tracking**: Returns detailed information about block changes, entity spawns, and command outcomes ### 2. get_player_info - Comprehensive Player Status Get detailed information about the player: - Position: Exact coordinates (x, y, z) and block positions - Orientation: Facing direction, yaw/pitch, cardinal direction - Calculated positions: Front position for building (3 blocks ahead) - Health & Status: Health, food level, experience - Game state: Current dimension, world time, game mode - Inventory: Selected slot, main hand/off-hand items Perfect for: Context-aware building, player-relative commands, status monitoring ### 3. get_blocks_in_area - World Analysis Scan rectangular areas to analyze structures: - Block detection: Returns all non-air blocks in specified area - Area limits: Configurable maximum area size (default: 50x50x50) - Structure analysis: Perfect for understanding existing builds - Build planning: Check areas before construction ### 4. take_screenshot - Visual Inspection Capture the current Minecraft game screen as an MCP image response. - Optional camera positioning: provide `x`, `y`, `z` to teleport before capture - Optional view control: provide `yaw`, `pitch` to set camera direction - Image output: returns Base64 PNG (`image/png`) for direct AI analysis - Great for build QA: verify structure shape, block placement, and surroundings visually - Supported from version **1.1.1+mc1.21.11** Important behavior: - If `x`, `y`, `z` are provided, the player is teleported. - If `yaw`, `pitch` are provided, the player view is changed. ## 🚀 How to Use ### Installation 1. Install Fabric Loader 0.16.14+ for Minecraft 1.21.4 2. Install Fabric API 0.119.3+1.21.4 3. Place this mod in your mods folder 4. Launch Minecraft - the MCP server starts automatically on http://localhost:8080/mcp #### ⚠️ Important: Command Permissions Before using AI command tools, command input must be allowed: - Single Player: When creating a world, set **Allow Cheats** to **ON** - Multiplayer / Dedicated Server: The player must have command permission (**OP** or equivalent server permission) #### ⚠️ Important: Disable "Pause on Lost Focus" CRITICAL STEP: You must disable Minecraft's "Pause on Lost Focus" setting to allow AI interactions while switching between applications: - Press F3 + P in-game to toggle off "Pause on Lost Focus" - You'll see a message confirming the setting change Without this change, the game will pause every time you switch to your AI editor, preventing commands from executing properly. ### Connecting AI Code Editors (Direct Support) #### Cursor IDE 1. Add MCP server configuration in Cursor settings 2. Use HTTP transport: http://localhost:8080/mcp 3. Start coding with AI assistance that can control Minecraft! ``` { "mcpServers": { "minecraft": { "url": "http://localhost:8080/mcp" } } } ``` #### Windsurf IDE 1. Configure MCP connection in Windsurf 2. Connect to: http://localhost:8080/mcp 3. Enable AI-powered Minecraft interactions #### VS Code with Extensions - GitHub Copilot: Configure MCP integration - Roo Code: Direct HTTP MCP support - Other MCP extensions: Compatible with streamable HTTP transport ### Connecting Other AI Assistants #### Claude Code Since Claude Code uses stdio transport, you'll need a proxy: 1. Install mcp-proxy or similar stdio-to-HTTP bridge 2. Configure proxy to convert stdio ↔ streamable HTTP 3. Connect Claude Code to the proxy ## Example AI Interactions "Build me a small house" → AI uses get_player_info to find your location, then execute_commands to place blocks "What blocks are around me?"→ AI uses get_blocks_in_area to scan nearby areas and reports findings "Clear this area and build a farm" → AI combines multiple tools to analyze, clear, and construct ## 🔧 Technical Details - Streamable HTTP transport: Full MCP protocol support over HTTP - Client-side mod: Runs entirely in the Minecraft client - Standards-compliant: Implements official Model Context Protocol specification - Block compression: Automatically optimizes block change representations - Chat capture: Monitors command outputs and game responses - Split environment: Uses Fabric's client/main source separation - Comprehensive logging: Detailed operation logs for debugging ## 🆘 Troubleshooting Server won't start? - Check if port 8080 is available - Verify Fabric API is installed - Check logs for configuration errors AI can't connect? - Ensure firewall allows localhost:8080 - Verify MCP client supports HTTP transport - For stdio clients, use mcp-proxy bridge Commands not working? - Verify you have appropriate permissions - Check "Pause on Lost Focus" is disabled (F3+P) - Review command syntax and limits Game keeps pausing? - Make sure "Pause on Lost Focus" is OFF (F3+P) - This is essential for AI interactions while multitasking ## 🔗 Links - Source Code: https://github.com/cuspymd/mcp-server-mod - Issue Tracker: https://github.com/cuspymd/mcp-server-mod/issues - MCP Specification: https://modelcontextprotocol.io - Fabric Documentation: https://fabricmc.net/wiki/