PaperMCP - Remote Minecraft Server Control via AI

Connect Claude (or any MCP client) to your remote Minecraft server from anywhere

PaperMCP enables AI assistants like Claude to monitor and manage your Minecraft server remotely through the Model Context Protocol (MCP). Perfect for server administrators who want AI-powered automation and monitoring.

Architecture

[Your PC]                                    [Remote Datacenter]
┌──────────────────────────┐                ┌────────────────────────┐
│ Claude Desktop           │                │ Minecraft Server       │
│         ↓                │                │   ┌─────────────────┐  │
│ PaperMCP Client          │◄───WebSocket───────│ PaperMCP Plugin │  │
│ (MCP Server on stdio)    │   (Internet)   │   │ (WS Server)     │  │
└──────────────────────────┘                │   └─────────────────┘  │
                                            └────────────────────────┘

Two Components:

PaperMCP Plugin - Runs on your Minecraft server, exposes WebSocket API
PaperMCP Client - Runs on your PC, connects Claude to the remote server

📚 Documentation

Complete Setup Guide - Step-by-step installation and configuration (START HERE!)
Usage Examples - Real-world examples of what you can do with AI + Minecraft
Quick Reference - Fast lookup for commands, configs, and troubleshooting

Features

Real-time Monitoring

Server health (TPS, memory, uptime)
Online players with locations and stats
Console logs and output
Player chat history

Server Management

Execute commands (with security controls)
Send messages to players
Manage time/weather/gamerules
Teleport players

Security

Token-based authentication
Command whitelist/blacklist with wildcards
Audit logging
IP whitelisting (optional)
Encrypted WebSocket connections (WSS)

Quick Start

1. Install Plugin on Minecraft Server

# Build the plugin
./gradlew :plugin:build

# Copy to your server
scp plugin/build/libs/PaperMCP-Plugin-1.0.0-SNAPSHOT.jar user@yourserver:/path/to/plugins/

Configure Plugin (plugins/PaperMCP/config.yml):

server:
  host: "0.0.0.0"         # Listen on all interfaces
  port: 25577              # WebSocket port
  authentication_token: "your-super-secret-token-here"  # CHANGE THIS!

mcp:
  security:
    command_whitelist:
      - "list"
      - "tps"
      - "time*"
      - "weather*"
      # Add more as needed

    command_blacklist:
      - "stop"
      - "*op*"
      - "ban*"
      # Blocks dangerous commands

Open Firewall Port:

# Allow WebSocket connections
sudo ufw allow 25577/tcp

2. Install Client on Your PC

# Build the client
./gradlew :client:build

# Copy client JAR to your PC
cp client/build/libs/PaperMCP-Client-1.0.0-SNAPSHOT.jar ~/papermcp/

Configure Client (papermcp-client-config.json):

{
  "host": "your-minecraft-server.com",
  "port": 25577,
  "token": "your-super-secret-token-here",
  "use_ssl": false,
  "reconnect": {
    "enabled": true,
    "max_attempts": 10,
    "delay_ms": 5000
  }
}

3. Configure Claude Desktop

Add to your Claude Desktop config:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "minecraft": {
      "command": "java",
      "args": [
        "-jar",
        "/full/path/to/PaperMCP-Client-1.0.0-SNAPSHOT.jar",
        "/full/path/to/papermcp-client-config.json"
      ]
    }
  }
}

4. Test It!

Start your Minecraft server (plugin auto-starts)
Restart Claude Desktop
Ask Claude: "What's the TPS on my Minecraft server?"

Available Tools

`minecraft_server_info`

Get server stats, TPS, version, player count

AI: "How's my server performing?"

`minecraft_list_players`

List online players with details

AI: "Who's online and where are they?"

`minecraft_read_console`

Read recent console output

AI: "Show me the last 50 console messages"

`minecraft_read_chat`

Read player chat history

AI: "What have players been talking about?"

`minecraft_execute_command`

Execute server commands (with security)

AI: "Set the time to day and clear the weather"

`minecraft_send_message`

Send messages to players

AI: "Announce that the server will restart in 10 minutes"

Use Cases

1. Automated Monitoring

AI: "Check server health every hour and notify me if TPS drops below 18"

2. Player Support

AI: "Monitor chat and respond to questions about server rules"

3. Administrative Tasks

AI: "If anyone complains about lag, check TPS and report back"

4. Event Management

AI: "At 8 PM, tp all players to spawn and announce the event"

Security Best Practices

🔒 Critical Security Steps

Change Default Token
- Use a long, random token (32+ characters)
- Never commit tokens to git
- Rotate tokens regularly

Use Command Whitelist

command_whitelist:
  - "list"      # Only allow specific commands
  - "tps"
  - "help"
# Empty whitelist = allow all (dangerous!)

Enable SSL/TLS
```
{
  "use_ssl": true  # In client config
}
```
Configure nginx/caddy reverse proxy for SSL termination

IP Whitelisting

allowed_ips:
  - "your.home.ip.address"
  - "your.office.ip.address/24"

Audit Logging

audit_logging: true  # Track all AI actions

Firewall Configuration

Only expose WebSocket port, not Minecraft port:

# Good: WebSocket on custom port
sudo ufw allow 25577/tcp

# Don't expose Minecraft port to internet if not needed
# sudo ufw allow 25565/tcp  # Only if players connect directly

SSL/TLS Setup (Recommended)

Use nginx or Caddy as reverse proxy:

Caddy (easiest):

your-minecraft-server.com:25577 {
    reverse_proxy localhost:25577
}

nginx:

server {
    listen 443 ssl;
    server_name mc.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:25577;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Then use wss://mc.yourdomain.com in client config.

Commands

Plugin Commands (In-Game)

/papermcp status - Show WebSocket server status
/papermcp clients - List connected clients
/papermcp reload - Reload configuration
/papermcp help - Show help

Client (Command Line)

# Run with default config (./papermcp-client-config.json)
java -jar PaperMCP-Client-1.0.0-SNAPSHOT.jar

# Run with custom config
java -jar PaperMCP-Client-1.0.0-SNAPSHOT.jar /path/to/config.json

# Enable debug logging
java -Dlogback.configurationFile=logback-debug.xml -jar PaperMCP-Client-1.0.0-SNAPSHOT.jar

Building from Source

Requirements:

Java 21 (for plugin)
Java 17+ (for client)

# Build everything
./gradlew build

# Build just plugin (requires Java 21)
./gradlew :plugin:build

# Build just client (requires Java 17+)
./gradlew :client:build

# Outputs:
# plugin/build/libs/PaperMCP-Plugin-1.0.0-SNAPSHOT.jar
# client/build/libs/PaperMCP-Client-1.0.0-SNAPSHOT.jar

Troubleshooting

Plugin Won't Start

Error: "Please set a secure authentication_token"

Edit plugins/PaperMCP/config.yml
Change CHANGE_ME_TO_A_SECURE_TOKEN to a random string

Port Already in Use

Change server.port in config.yml
Or stop conflicting service: sudo lsof -i :25577

Client Can't Connect

Authentication Failed

Ensure tokens match in plugin and client configs
Tokens are case-sensitive

Connection Refused

Check firewall: sudo ufw status
Verify port is open: telnet yourserver.com 25577
Check plugin logs: logs/latest.log

SSL/TLS Errors

If using use_ssl: true, ensure reverse proxy is configured
Check certificate validity
Try with use_ssl: false first to isolate issue

Claude Desktop Not Seeing Tools

Tools Don't Appear

Restart Claude Desktop after config changes
Check client logs for errors
Verify JSON syntax in claude_desktop_config.json

"Request timed out"

Client may not be connected to server
Check client logs
Verify server is running: /papermcp status

Development

Project Structure

PaperMCP/
├── plugin/                       # Minecraft server plugin
│   └── src/main/kotlin/com/badgersmc/papermcp/
│       ├── PaperMCPPlugin.kt    # Main plugin class
│       ├── bridge/              # Minecraft API bridge
│       │   ├── MinecraftBridge.kt
│       │   └── EventListeners.kt
│       └── websocket/           # WebSocket server
│           ├── WebSocketServer.kt
│           └── RequestHandler.kt
│
└── client/                       # PC client application
    └── src/main/kotlin/com/badgersmc/papermcp/client/
        ├── PaperMCPClient.kt    # Main entry point
        ├── ClientConfig.kt      # Configuration
        ├── websocket/           # WebSocket client
        │   └── WebSocketClient.kt
        └── mcp/                 # MCP protocol
            ├── MCPProtocolHandler.kt
            └── ToolRegistry.kt

Adding New Tools

1. Add method to RequestHandler.kt (plugin)

private fun handleMyNewTool(id: Any?, params: JsonObject?): JsonObject {
    // Implement tool logic
    return createSuccess(id, result)
}

2. Add tool to ToolRegistry.kt (client)

class MyNewTool : MCPTool {
    override val name = "minecraft_my_tool"
    override val definition = ToolDefinition(...)
    override fun execute(client: WebSocketClient, arguments: JsonObject) =
        client.sendRequest("my_new_tool", arguments)
            .thenApply { it.get("result").asJsonObject }
}

Running Tests

./gradlew test

Roadmap

FAQ

Q: Is this secure for production use? A: With proper configuration (strong tokens, command whitelist, SSL, IP filtering), yes. Always audit what AI has access to.

Q: Does this work with Forge/Fabric? A: Currently only Paper/Spigot. Forge/Fabric support planned.

Q: Can multiple people connect? A: Yes, the WebSocket server supports multiple concurrent clients.

Q: What's the performance impact? A: Minimal. The plugin uses async I/O and runs on separate threads.

Q: Does this work with BungeeCord/Velocity? A: Yes, install the plugin on each backend server. Proxy support coming soon.

Q: What Java version is required? A: The plugin requires Java 21 (for Minecraft 1.21+). The client requires Java 17+. Make sure your server is running Java 21 before installing the plugin.

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

Support

Issues: GitHub Issues
Pull Requests: Contributions welcome!
Docs: See the markdown files in this repository

Credits

Built with ❤️ by BadgersMC

Technologies:

Model Context Protocol by Anthropic
Paper MC - High-performance Minecraft server
Javalin - Lightweight web framework
Kotlin - Modern JVM language

⚠️ Disclaimer: This tool gives AI access to your Minecraft server. Use appropriate security measures and only connect trusted AI clients. The authors are not responsible for any damage caused by misconfiguration or misuse.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
client		client
gradle/wrapper		gradle/wrapper
plugin		plugin
src/main		src/main
.gitignore		.gitignore
BUILD_INSTRUCTIONS.md		BUILD_INSTRUCTIONS.md
QUICK_REFERENCE.md		QUICK_REFERENCE.md
README.md		README.md
SETUP_GUIDE.md		SETUP_GUIDE.md
USAGE_EXAMPLES.md		USAGE_EXAMPLES.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

BadgersMC/PaperMCP

Folders and files

Latest commit

History

Repository files navigation