🤖 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

🚀 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: 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:

Method 1 - Keyboard Shortcut (Recommended):

• Press F3 + P in-game to toggle off "Pause on Lost Focus"
• You'll see a message confirming the setting change

Method 2 - Game Settings:

1. Go to Options → Video Settings
2. Find "Pause on Lost Focus" setting
3. Set it to OFF

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!

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

🛡️ Safety Features

• Command filtering: Only allows safe, non-destructive commands
• Area limits: Prevents excessive modifications (>50x50x50 blocks)
• Entity limits: Restricts mass entity creation
• No griefing: Blocks commands like kill @a or global mode changes
• Async execution: Commands run without blocking the main thread

🎯 Perfect For

• AI-powered coding: Use Cursor, Windsurf, or VS Code to control Minecraft while coding
• AI-assisted building: Let AI help design and construct structures
• Automated development: Build test environments and structures programmatically
• Educational content: Demonstrate AI integration with games
• Content creation: Use AI for rapid prototyping and building
• Game automation: Create AI-driven redstone contraptions and farms

🔧 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/