A Minecraft Paper plugin that implements the Model Context Protocol (MCP) over HTTP, enabling AI assistants like Claude Desktop to securely manage your Minecraft server.
Overview
MinecraftMCP provides a JSON-RPC 2.0 over HTTP implementation of the Model Context Protocol, allowing AI assistants to interact with your Minecraft server through a standardized interface. The plugin offers secure, controlled access to server management functions through six specialized tools.
Minecraft mcp server
Key Features
HTTP-Only MCP Implementation: Clean JSON-RPC 2.0 over HTTP protocol
Secure Authentication: API key-based authentication with session management
Real-time Communication: Server-Sent Events (SSE) for live updates
Command Safety: Comprehensive command whitelisting and validation
Rate Limiting: Configurable request throttling and abuse protection
Six Core Tools: Complete server management through specialized MCP tools
Requirements
Paper Server: 1.21.4 or later (Paper-specific features required)
Java: 21 or later
Dependencies: Jackson (2.15.2), Jetty (11.0.19) - auto-included via maven shade
Installation
Download the plugin JAR from releases
Place in your server's plugins/ directory
Restart your server
Configure the plugin by editing plugins/MinecraftMCP/config.yml
Set a secure API key in the configuration
Restart server to apply configuration
Configuration
The plugin creates a comprehensive configuration file at plugins/MinecraftMCP/config.yml:
includeChunks (boolean, optional): Include chunk information
Claude Desktop Integration
Important Note: This project is a Paper plugin that runs an embedded HTTP server, not a standard MCP server that can be directly integrated with Claude Desktop using the typical command/args configuration.
Architecture Overview
MinecraftMCP works differently from standard MCP servers:
Standard MCP servers are standalone executables that Claude Desktop launches using command and args
MinecraftMCP is a Paper plugin that runs inside your Minecraft server and exposes MCP functionality via HTTP
Integration Options
Option 1: HTTP API Access
While not directly compatible with Claude Desktop's MCP integration, you can interact with the server using HTTP requests:
# Example: Get server status
curl -X POST http://localhost:25575/mcp \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_server_status",
"arguments": {}
}
}'
Option 2: MCP Bridge (Future Development)
To enable true Claude Desktop integration, you would need:
MCP Bridge Application: A standalone program that:
Implements standard MCP protocol (stdio/command interface)
Forwards requests to MinecraftMCP's HTTP API
Translates between MCP and HTTP protocols
Current Limitations
No direct Claude Desktop MCP integration - requires HTTP API calls or bridge development
Plugin dependency - must run inside a Paper Minecraft server
Server-specific - tied to a particular Minecraft server instance
Getting Started
Install the plugin on your Paper server
Configure API keys and security settings
Use HTTP API directly or develop/wait for an MCP bridge
Access server management through HTTP requests
Commands
The plugin adds these in-game commands:
/mcp status - Check MCP server status
/mcp reload - Reload configuration (requires op)
/mcp start - Start MCP server (requires op)
/mcp stop - Stop MCP server (requires op)
/mcp help - Show help information
Security
Authentication Flow
Client sends request with X-API-Key header
Plugin validates API key against configuration
Session created with UUID and timeout
Requests validated against session and rate limits
Security Features
API Key Authentication: Required for all requests
Command Whitelisting: Only pre-approved commands allowed