Minecraft

🚀 Minecraft MCP Integration

This is an integration of the Model Context Protocol (MCP), enabling AI assistants to interact with Minecraft servers. It allows AI models to observe and interact with the Minecraft world through bots.

🚀 Quick Start

Prerequisites

1. Minecraft Launcher
2. Node.js 18 or higher
3. Claude Desktop Application
4. Java 21.0.5 (recommended)

⚠️ Important Note

Currently, this integration has only been tested on macOS/Linux. Compatibility with Windows is not guaranteed.

Key Considerations

1. Use the F3+P shortcut: Press F3 and P simultaneously. This toggles the "Pause on Lost Focus" feature. After turning it off, you can switch back to the Claude desktop application while keeping Minecraft running without pausing.

2. Connection issues when restarting Claude: If you restart Claude while the Minecraft server is running, subsequent attempts to start the MCP connection may fail due to lingering Java processes. Refer to the troubleshooting steps in FAQ: MCP Connection Failure for solutions.

Installation Steps

1. Download and set up the Minecraft server

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

2. Install and configure the MCP integration

   Quick installation (recommended):

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

   Follow the CLI prompts to complete the setup.

   Or, manual setup:

   • Navigate to ~/Library/Application Support/Claude/claude_desktop_config.json.
   • Add the following content to the file:

     {
       "mcpIntegration": {
         "enabled": true,
         "serverPath": "/path/to/minecraft-server",
         "jarName": "server.jar"
       }
     }
     

   • Launch the Claude desktop application and enable the MCP integration feature.

3. Verify the installation

   • Ensure that Java and Node.js are correctly installed.
   • Check that the server.jar file exists and the path is correct.
   • Try starting the Minecraft server to ensure it runs properly.

Notes

• Additional dependencies may be required on the first run. Install the necessary packages as prompted.
• If you encounter issues, check the log files for more information.

✨ Features

• Bot control: Control in - game characters via the MCP interface.
• Data exchange: Transfer real - time data between the game and the AI.
• Script support: Write custom scripts using Node.js to extend functionality.

📚 Documentation

FAQ

1. Unable to connect to the server

   • Ensure that the Minecraft server is running.
   • Check if you are using "localhost" as the server address.
   • Review your firewall settings to ensure port 25565 is available.

2. Server fails to start

   • Verify that Java is installed.
   • Check the path of server.jar.
   • Ensure that port 25565 is not occupied.

3. Java process not terminated

   • On Mac/Linux, use the jps command to find Java processes.
   • Use the Task Manager (Windows) or Activity Monitor (Mac/Linux) to force - terminate the process.
   • If manual termination is not possible, restart your computer.

Log Locations

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

🤝 Contribution

All contributions, big or small, are welcome!

📄 License

This project is open - sourced under the MIT License. See the LICENSE file for details.