minecraft-mcp-client

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:

• Download the MinecraftMCP plugin JAR from releases
• Place it in your Paper server's plugins/ directory
• Configure the plugin with a secure API key
• 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:

• Claude Desktop connects to this client via stdio transport
• This client proxies all MCP requests to your Minecraft server via HTTP
• Your Minecraft server processes the requests and returns responses
• 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