Mod
A Fabric mod that implements a Model Context Protocol (MCP) server, enabling AI assistants like Claude to interact with Minecraft through structured commands.
Ask AI about Mod
Powered by Claude ยท Grounded in docs
I know everything about Mod. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
- Install Fabric Loader for Minecraft 1.21.11
- Download and install Fabric API
- Place the mod JAR file in your
modsfolder - 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_screenshottool, which uses the local game window. - Dedicated Server Mode: Has access to tools like
execute_commands,get_player_info, andget_blocks_in_area, enabling full AI manipulation of the world without rendering. Thetake_screenshottool is disabled in server mode since there is no rendering context. Note thatget_player_infocurrently 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 validationget_player_info- Get comprehensive player informationget_blocks_in_area- Scan and retrieve blocks in a specified areatake_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 blockssummon villager ~ ~ ~- Spawn entitiessetblock ~ ~1 ~ oak_door- Place specific blockstp @s ~ ~10 ~- Teleport playersgive @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 sessionPOST /mcp/ping- Health checkPOST /mcp/tools/list- List available toolsPOST /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 statusvalues: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 coordinatesto(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.
- Open
config/mcp.json. - Set
"save_screenshots_for_debug": truein theclientsection. - Screenshots will be saved to the
mcp_debug_screenshots/directory in your Minecraft instance folder. - Files are named using the pattern:
screenshot_YYYYMMDD_HHMMSS_SSS.png.
License
This project is licensed under the CC0-1.0 License.
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Test thoroughly (See TESTING.md for more info)
- Submit a pull request
Support
For issues and questions:
- Check the Issues page
- Review the configuration documentation
- Enable debug logging for detailed troubleshooting
