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:

4. Install mcp-proxy or similar stdio-to-HTTP bridge
5. Configure proxy to convert stdio ↔ streamable HTTP

6. 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/