Mod

A Fabric mod that implements a Model Context Protocol (MCP) server, enabling AI assistants like Claude to interact with Minecraft through structured commands.

Overview

This mod creates an HTTP server within the Minecraft client or dedicated server that accepts MCP protocol requests, allowing Large Language Models to execute Minecraft commands safely and efficiently. The mod includes comprehensive safety validation to prevent destructive operations.

It is designed to be fully compatible with both Single-Player (Integrated Server) and Multiplayer Dedicated Servers.

Features

• Server and Client Support: Works on both single-player and dedicated server environments.
• MCP Protocol Support: Full implementation of Model Context Protocol for AI interaction
• Safety Validation: Comprehensive command filtering and validation system
• Asynchronous Execution: Non-blocking command execution to maintain game performance
• Configurable Settings: Customizable safety limits, server settings, and command permissions
• Real-time Feedback: Detailed execution results including block counts and entity information

Requirements

• Minecraft: 26.2
• Fabric Loader: 0.19.3 or higher
• Fabric API: 0.154.1+26.2 or higher compatible 26.2 build
• Java: 25 or higher

Installation

1. Install Fabric Loader for Minecraft 26.2
2. Download and install a Minecraft 26.2-compatible Fabric API
3. Place the mod JAR file in your mods folder
4. Launch Minecraft with the Fabric profile

Minecraft 26.2 is unobfuscated. This mod is built against Mojang official names and does not use Yarn mappings.

Usage

Starting the MCP Server

The MCP server starts automatically when you launch Minecraft with the mod installed. By default, it runs on localhost:8080.

Important Command Permission Settings

Before using AI command tools, make sure command input is allowed in your current game mode:

• Single Player: When creating a world, set Allow Cheats to ON.
• Multiplayer / Dedicated Server: The player running commands must have server permission (for example, OP or equivalent permission from your server permission plugin).

To keep AI interactions working while switching between applications:

• Disable Pause on Lost Focus by pressing F3 + P in-game.
• Minecraft will show a confirmation message when the setting is toggled.
• If this is left enabled, the game pauses when Minecraft loses focus and AI-issued commands will not execute.

Server vs Client Modes

The mod detects if it is running in a Client (Single Player) or a Dedicated Server environment:

• Client Mode: Full feature support, including the take_screenshot tool, which uses the local game window.
• Dedicated Server Mode: Has access to tools like execute_commands, get_player_info, and get_blocks_in_area, enabling full AI manipulation of the world without rendering. The take_screenshot tool is disabled in server mode since there is no rendering context. Note that get_player_info currently selects the first online player on the server to report its location.

If playing Single Player, the integrated server logic runs through the client-side MCP.

Configuration

The mod creates a configuration file at config/mcp.json:

{
  "server": {
    "port": 8080,
    "host": "localhost",
    "enable_safety": true,
    "max_area_size": 50,
    "allowed_commands": ["fill", "clone", "setblock", "summon", "tp", "give"],
    "request_timeout_ms": 30000
  },
  "client": {
    "auto_start": true,
    "show_notifications": true,
    "log_level": "INFO",
    "log_commands": false,
    "save_screenshots_for_debug": false
  },
  "safety": {
    "max_entities_per_command": 10,
    "max_blocks_per_command": 125000,
    "block_creative_for_all": true,
    "require_op_for_admin_commands": true
  }
}

server.request_timeout_ms limits how long the server waits for tool execution (including execute_commands and take_screenshot) before returning a timeout error.

Connecting with AI Assistants

Connect your AI assistant (like Claude) to the MCP server using the endpoint:

http://localhost:8080/mcp

The server supports three main tools:

• execute_commands - Execute Minecraft commands with safety validation
• get_player_info - Get comprehensive player information
• get_blocks_in_area - Scan and retrieve blocks in a specified area
• take_screenshot - Capture game screen with optional camera control

Example Commands

The AI can execute commands like:

• fill ~ ~ ~ ~10 ~5 ~8 oak_planks - Fill an area with blocks
• summon villager ~ ~ ~ - Spawn entities
• setblock ~ ~1 ~ oak_door - Place specific blocks
• tp @s ~ ~10 ~ - Teleport players
• give @s diamond_sword - Give items

Safety Features

Allowed Commands

• Building: fill, clone, setblock
• Entities: summon, tp, teleport
• Items: give
• Game state: gamemode, effect, enchant, weather, time
• Communication: say, tell, title

Blocked Operations

• Mass entity destruction (kill @a, kill @e)
• Excessive area operations (>50×50×50 blocks)
• Mass item generation (>100 items)
• Global creative mode assignment

Development

Building

./gradlew build

Running in Development

./gradlew runClient

Project Structure

src/
├── main/java/cuspymd/mcp/mod/
│   ├── MCPServerMod.java           # Main mod class
│   ├── MCPServerModClient.java     # Client initializer
│   ├── server/                     # MCP server implementation
│   ├── command/                    # Command execution system
│   ├── config/                     # Configuration management
│   └── utils/                      # Utility classes
└── main/resources/
    ├── fabric.mod.json             # Mod metadata
    └── *.mixins.json              # Mixin configurations

API Reference

MCP Endpoints

• POST /mcp/initialize - Initialize MCP session
• POST /mcp/ping - Health check
• POST /mcp/tools/list - List available tools
• POST /mcp/tools/call - Execute commands

Tool: execute_commands

Execute one or more Minecraft commands sequentially with safety validation.

Parameters:

• commands (array): List of Minecraft commands (without leading slash)
• validate_safety (boolean): Enable safety validation (default: true)

Response schema (text payload JSON):

• Top-level: totalCommands, acceptedCount, appliedCount, failedCount, results, chatMessages
• Per command: index, command, status, accepted, applied, summary, chatMessages
• status values: applied, rejected_by_game, execution_error, timed_out, rejected_by_safety, unknown

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "execute_commands",
    "arguments": {
      "commands": [
        "fill ~ ~ ~ ~10 ~5 ~8 oak_planks",
        "setblock ~5 ~6 ~4 oak_door"
      ],
      "validate_safety": true
    }
  }
}

Tool: get_player_info

Get comprehensive player information including position, facing direction, health, inventory, and game state.

Parameters: None required

Response includes:

• Exact position (x, y, z coordinates) and block coordinates
• Facing direction (yaw, pitch, cardinal direction)
• Calculated front position for building (3 blocks ahead)
• Look vector for directional calculations
• Health, food, and experience status
• Current game mode and dimension
• World time information
• Inventory details (selected slot, main/off-hand items)

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "get_player_info",
    "arguments": {}
  }
}

Tool: get_blocks_in_area

Scan and retrieve all non-air blocks within a specified rectangular area. Useful for analyzing structures or checking build areas.

Parameters:

• from (object): Starting position with x, y, z coordinates
• to (object): Ending position with x, y, z coordinates

Response includes:

• List of all non-air blocks in the area
• Block types and positions
• Total block count
• Area dimensions and validation info

Example Request:

{
  "method": "tools/call", 
  "params": {
    "name": "get_blocks_in_area",
    "arguments": {
      "from": {"x": 100, "y": 64, "z": 200},
      "to": {"x": 110, "y": 74, "z": 210}
    }
  }
}

Note: Maximum area size per axis is limited by server configuration (default: 50 blocks).

Tool: take_screenshot

Capture a screenshot of the current Minecraft game screen. Optionally, you can specify coordinates and rotation to move the player and set their gaze before taking the screenshot.

Parameters:

• x (number, optional): X coordinate to teleport the player to.
• y (number, optional): Y coordinate to teleport the player to.
• z (number, optional): Z coordinate to teleport the player to.
• yaw (number, optional): Yaw rotation (0-360) for horizontal view.
• pitch (number, optional): Pitch rotation (-90 to 90) for vertical view.

Response includes:

• Base64 encoded PNG image data.
• MIME type (image/png).

Example Request:

{
  "method": "tools/call",
  "params": {
    "name": "take_screenshot",
    "arguments": {
      "x": 120.5,
      "y": 70,
      "z": -200.5,
      "yaw": 180,
      "pitch": 0
    }
  }
}

Debugging

Local Screenshot Storage

For debugging purposes, you can enable local saving of every screenshot captured by the MCP server.

1. Open config/mcp.json.
2. Set "save_screenshots_for_debug": true in the client section.
3. Screenshots will be saved to the mcp_debug_screenshots/ directory in your Minecraft instance folder.
4. Files are named using the pattern: screenshot_YYYYMMDD_HHMMSS_SSS.png.

License

This project is licensed under the CC0-1.0 License.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly (See TESTING.md for more info)
5. Submit a pull request

Support

For issues and questions:

• Check the Issues page
• Review the configuration documentation
• Enable debug logging for detailed troubleshooting