Minecraft MCP Client

A bridge client that connects Claude Desktop to Minecraft servers running the MinecraftMCP Paper plugin.

Installation

This package is designed to be used with NPX, so no installation is required:

npx minecraft-mcp-client --server http://localhost:25575 --api-key your-api-key

Prerequisites

You need the MinecraftMCP Paper plugin installed and running on your Minecraft server:

1. Download the MinecraftMCP plugin JAR from releases
2. Place it in your Paper server's plugins/ directory
3. Configure the plugin with a secure API key
4. Ensure the MCP server is enabled on port 25575 (or your custom port)

Usage

With Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": [
        "-y",
        "minecraft-mcp-client",
        "--server",
        "http://localhost:25575",
        "--api-key",
        "your-secure-api-key-from-plugin-config"
      ]
    }
  }
}

Important: Replace your-secure-api-key-from-plugin-config with the actual API key you configured in the MinecraftMCP plugin's config.yml.

Command Line Options

• -s, --server <url>: Required - Minecraft MCP server URL (e.g., http://localhost:25575)
• -k, --api-key <key>: Required - API key for authenticating with the Minecraft MCP server
• -v, --verbose: Enable verbose logging (default: false)
• -h, --help: Display help information

Example

npx minecraft-mcp-client --server http://localhost:25575 --api-key my-secure-api-key --verbose

How It Works

This client acts as a bridge between Claude Desktop and your Minecraft MCP server:

1. Claude Desktop connects to this client via stdio transport
2. This client proxies all MCP requests to your Minecraft server via HTTP
3. Your Minecraft server processes the requests and returns responses
4. This client forwards the responses back to Claude Desktop

Requirements

• Node.js 16.0.0 or higher
• A running Minecraft MCP server
• Valid API key for your Minecraft MCP server

Available Minecraft Tools

When connected, Claude Desktop will have access to these Minecraft management tools:

• minecraft_execute_command - Execute server commands safely
• minecraft_server_status - Get server metrics (TPS, memory, players)
• minecraft_server_logs - Retrieve and filter server logs
• minecraft_player_list - List online players with details
• minecraft_manage_player - Kick, ban, teleport, change gamemode
• minecraft_world_info - Get world information and stats

Supported MCP Features

• ✅ Initialize - Proper MCP handshake with version negotiation
• ✅ Tools - List and call all Minecraft management tools
• ✅ Resources - List and read server resources (planned)
• ✅ Prompts - List and get server prompts (planned)
• ✅ Authentication - X-API-Key header authentication
• ✅ Error Handling - Comprehensive error reporting and connection testing

Troubleshooting

Common Issues

"Cannot connect to Minecraft MCP server"

• Verify your Minecraft server is running
• Check that the MinecraftMCP plugin is installed and enabled
• Confirm the server is listening on the correct port (default: 25575)
• Ensure no firewall is blocking the connection

"Authentication failed"

• Double-check your API key matches the one in the plugin's config.yml
• Make sure the API key doesn't have extra spaces or quotes
• Verify the plugin's authentication is enabled

"MCP server endpoint not found"

• Confirm the MinecraftMCP plugin is properly installed
• Check that the plugin loaded successfully in the server logs
• Verify the MCP server is enabled in the plugin configuration

Version Compatibility

• minecraft-mcp-client: 2.1.0+
• MinecraftMCP Plugin: 1.0.5+
• MCP Protocol: 2024-11-05
• Paper Server: 1.21.4+

License

MIT