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 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: 1.21.11
• Fabric Loader: 0.18.4 or higher
• Fabric API: 0.141.3+1.21.11 or higher
• Java: 21 or higher

Installation

1. Install Fabric Loader for Minecraft 1.21.11
2. Download and install Fabric API
3. Place the mod JAR file in your mods folder
4. 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.

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 pl

... View full README on GitHub