Minecraft MCP server

This MCP server allows AI assistants like Claude to interact with a Minecraft server through a bot. The integration enables AI models to observe the game world and control a character within Minecraft.

Prerequisites

• Minecraft Launcher
• Node.js 18 or higher
• Claude Desktop App
• Java 21.0.5 (recommended)

⚠️ Note: Currently only tested on macOS/Linux. Windows compatibility is not guaranteed.

Important Configuration Steps

Toggle Pause on Lost Focus

Press F3 + P together to turn off the "Pause on Lost Focus" feature. This allows you to switch to Claude desktop while keeping Minecraft running.

Connection Issue Awareness

If you restart Claude while the Minecraft server is running, you may experience MCP connection issues due to lingering Java processes. See the Troubleshooting section for resolution steps.

Installation

1. Download and Setup Minecraft Server

• Download Minecraft server v1.21 from mcversions.net/1.21
• Install Java 21.0.5 if not already installed
• Create a dedicated directory (e.g., ~/minecraft-server/)
• Place the downloaded server.jar file in this directory
• Note the absolute path to your server.jar file

2. Install and Configure MCP Integration

Quick Install (Recommended):

npx -y @smithery/cli install mcp-minecraft --client claude

Follow the CLI prompts to complete the setup.

Manual Setup:

• Navigate to ~/Library/Application Support/Claude/claude_desktop_config.json
• Add the MCP server configuration:

{
  "mcpServers": {
    "mcp-minecraft": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-minecraft@latest",
        "--server-jar",
        "/absolute/path/to/minecraft-server/server.jar"
      ]
    }
  }
}   

⚠️ Replace /absolute/path/to/minecraft-server/server.jar with your actual server.jar path

3. Launch Claude Desktop

Start Claude Desktop after completing the configuration.

4. Connect to Server

• Open Minecraft Launcher
• Install and launch Minecraft Java Edition v1.21
• Click "Play" and Select "Multiplayer"
• Click "Add Server"
• Enter server details:
  • Server Name: Minecraft Server
  • Server Address: localhost:25565
• Click "Done"

Available Features

Resources

The integration exposes these MCP resources:

• minecraft://bot/location - Current bot position in the world
• minecraft://bot/status - Bot connection status

Tools

Available MCP tools:

• chat - Send chat messages to the server
• jump - Make the bot jump
• moveForward - Make the bot move forward
• moveBack - Make the bot move backward
• turnLeft - Make the bot turn left
• turnRight - Make the bot turn right
• placeBlock - Place a block at specified coordinates
• digBlock - Break a block at specified coordinates
• getBlockInfo - Get information about a block at specified coordinates
• selectSlot - Select a hotbar slot (0-8)
• getInventory - Get contents of bot's inventory
• equipItem - Equip an item by name to specified destination
• getStatus - Get bot's current status (health, food, position, etc.)
• getNearbyEntities - Get list of nearby entities within range
• attack - Attack a nearby entity by name
• useItem - Use/activate the currently held item
• stopUsingItem - Stop using/deactivate the current item
• lookAt - Make the bot look at specific coordinates
• followPlayer - Follow a specific player
• stopFollowing - Stop following current target
• goToPosition - Navigate to specific coordinates

Technical Details

• Server runs in offline mode for local development
• Default memory allocation: 2GB
• Default port: 25565
• Bot username: MCPBot

Troubleshooting

MCP Connection Failed

• Look for lingering Java processes
• Terminate them manually:
  • Windows: Use Task Manager
  • Mac/Linux: Go to 'Activity Monitor' and 'Force Quit' java
• Restart computer if process termination fails
• Note: Latest version should auto-resolve these issues

Server Won't Start

• Verify Java is installed
• Check server.jar path is correct
• Ensure port 25565 is available

Can't Connect to Server

• Verify server is running (check logs)
• Confirm you're using "localhost" as server address
• Check firewall settings

Logs Location

• Minecraft Server logs: Check the minecraft-server directory
• Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.