Minemcp

🚀 MineMCP

A Minecraft Paper plugin that implements the Model Context Protocol (MCP) server, enabling AI agents to control and monitor a Minecraft 1.21 server via HTTP.

🚀 Quick Start

MineMCP is a Minecraft Paper plugin that allows AI agents to interact with a Minecraft 1.21 server through HTTP. It offers a variety of tools for world manipulation, command execution, file system access, and server information retrieval.

✨ Features

World Manipulation

• pose_block: Place a block at specific coordinates.
• break_block: Break a block at specific coordinates.
• fill_block: Fill a region with blocks.

Command Execution

• execute_command: Execute any Minecraft command with output capture.

File System

• read_file: Read text files from the server.
• write_file: Write text files to the server.
• read_file_base64: Read binary files as Base64.
• write_file_base64: Write binary files from Base64.
• list_directory: List directory contents.

Server Information

• list_plugins: Get all installed plugins.
• get_logs: Retrieve recent server logs.
• get_online_players: List all online players.
• get_player: Get detailed information about a specific player (health, inventory, location, effects, etc.).

📦 Installation

Download Pre-built JAR

1. Download the latest release from the Releases page.
2. Place MineMCP-1.0.0-all.jar in your server's plugins/ folder.
3. Start/restart your server.
4. Configure the token in plugins/MineMCP/config.yml.

⚙️ Configuration

After the first run, edit plugins/MineMCP/config.yml:

server:
  port: 3000
  token: "your-secret-token-here"  # Change this to a secure random token!

⚠️ Important Note

Always change the default token for security!

Generating a Secure Token

# Linux/macOS
openssl rand -hex 32

# Or use any password generator to create a strong token

💻 Usage Examples

Starting the Server

1. Start your Minecraft server with MineMCP installed.
2. The MCP server will automatically start on port 3000 (configurable).
3. Check the console for: [MineMCP] MCP server started on port 3000.

Connecting with an MCP Client

Using VS Code with MCP Extension

Create or edit .vscode/mcp.json in your project:

{
  "mcpServers": {
    "minecraft": {
      "url": "http://localhost:3000/sse?token=your-secret-token-here"
    }
  }
}

API Examples

Execute a Command

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_command",
    "arguments": {
      "command": "time set day"
    }
  }
}

Place a Block

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pose_block",
    "arguments": {
      "world": "world",
      "x": 100,
      "y": 64,
      "z": 200,
      "material": "DIAMOND_BLOCK"
    }
  }
}

Get Player Information

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_player",
    "arguments": {
      "player": "PlayerName",
      ...
    }
  }
}

🔧 Technical Details

Security Considerations

1. Token Protection: Never commit your token to version control.
2. Network Security: By default, the server binds to 0.0.0.0 (all interfaces).
3. Firewall Rules: Restrict port 3000 access to trusted IPs only.
4. File System Access: Tools have access to the entire server directory - use with caution.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

Adding a New Tool

1. Create a new class extending McpTool in src/main/java/me/axeno/minemcp/tools/impl/.
2. Implement the required methods (getSchema() and execute()).
3. Register the tool in ToolHandler.java constructor.

Example:

public class MyTool extends McpTool {
    public MyTool() {
        super("my_tool", "Description of my tool");
    }

    @Override
    public ObjectNode getSchema() {
        ObjectNode schema = mapper.createObjectNode();
        schema.put("type", "object");
        // Define your schema...
        return schema;
    }

    @Override
    public ObjectNode execute(JsonNode args) throws Exception {
        CompletableFuture<String> future = new CompletableFuture<>();
        
        Bukkit.getScheduler().runTask(MineMCP.getInstance(), () -> {
            try {
                // Your Bukkit operations here
                future.complete("Success!");
            } catch (Exception e) {
                future.completeExceptionally(e);
            }
        });
        
        String result = future.get(10, TimeUnit.SECONDS);
        return createTextResult(result);
    }
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• Issues: GitHub Issues

Made with ❤️ for the Minecraft and AI communities