mcp-server-mod by cuspymd - MCP Server

Minecraft MCP Server 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 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.

Features

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: 1.21.4
Fabric Loader: 0.16.14 or higher
Fabric API: 0.119.3+1.21.4
Java: 21 or higher

Installation

Install Fabric Loader for Minecraft 1.21.4
Download and install Fabric API
Place the mod JAR file in your mods folder
Launch Minecraft with the Fabric profile

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.

Configuration

The mod creates a configuration file at config/mcp-client.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
  },
  "safety": {
    "max_entities_per_command": 10,
    "max_blocks_per_command": 125000,
    "block_creative_for_all": true,
    "require_op_for_admin_commands": true
  }
}

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

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)

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).

License

This project is licensed under the CC0-1.0 License.

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

Support

For issues and questions:

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