Minecraft MCP Server

# Fundamental Labs/Minecraft Client This library is the Client library for a Minecraft Game Skills and MCP Integration. Fairies MCP Client (<https://fairies.ai/>) also supports direct connection with a single click. ## Features - **Full Minecraft Control**: Connect AI agents to Minecraft servers and control bots - **30 Verified Skills**: Pre-built, tested skills for common Minecraft tasks - **Flexible Connection**: Connect to any Minecraft server with optional per-bot configuration - **Multi-Bot Support**: Manage multiple bots simultaneously - **MCP Standard**: Compatible with any MCP client (Claude Desktop, etc.) ## Installation ### Direct call via npx (Recommended) ```bash npx --y -- @fundamentallabs/minecraft-mcp ``` ### Via npm (Recommended) ```bash npm install -g @fundamentallabs/minecraft-mcp ``` ### From Source ```bash git clone https://github.com/FundamentalLabs/minecraft-mcp.git cd minecraft-mcp/minecraft-client/mcp-server npm install npm run build ``` ## Usage ### Starting the Server You can start the MCP server with optional default connection settings: ```bash # Start with no defaults (connection specified per bot) minecraft-mcp # Start with default connection settings minecraft-mcp -h play.example.com -p 25565 ``` ### Command Line Options ```bash Options: -p, --port <port> Minecraft server port (default: 25565) -h, --host <host> Minecraft server host (default: localhost) --help Display help ``` ### Integration with Claude Desktop or JSON configurations Locally Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): For remote installation (recommended) ```json { "mcpServers": { "minecraft": { "command": "npx", "args": ["-y", "-- @fundamentallabs/minecraft-mcp"] } } } ``` If running locally from source: ```json { "mcpServers": { "minecraft": { "command": "node", "args": ["/path/to/minecraft-mcp/minecraft-client/mcp-server/dist/mcp-server.js"] } } } ``` Replace `/path/to/minecraft-mcp` with the actual path where you cloned the repository. ### Integration with Other MCP Clients The server uses stdio transport and can be integrated with any MCP client: ```bash # Using the MCP inspector for testing cd minecraft-client/mcp-server npx @modelcontextprotocol/inspector node dist/mcp-server.js -- -p 25565 ``` ## Available Skills ### Bot Management - **joinGame** - Spawn a new bot into the Minecraft game - `username` (required): Bot's username - `host` (optional): Server host (defaults to 'localhost' or command line option) - `port` (optional): Server port (defaults to 25565 or command line option) - **leaveGame** - Disconnect bot(s) from the game - `username` (optional): Specific bot to disconnect - `disconnectAll` (optional): Disconnect all bots if true ### Movement & Navigation - **goToSomeone** - Navigate to another player - **goToKnownLocation** - Navigate to specific coordinates - **runAway** - Run away from threats - **swimToLand** - Swim to nearest land when in water ### Combat & Hunting - **attackSomeone** - Attack players, mobs, or animals - **hunt** - Hunt animals or mobs ### Resource Gathering - **mineResource** - Mine specific blocks or resources - **harvestMatureCrops** - Harvest mature crops from farmland - **pickupItem** - Pick up items from the ground ### Crafting & Smelting - **craftItems** - Craft items using a crafting table - **cookItem** - Cook items in a furnace - **smeltItem** - Smelt items in a furnace - **retrieveItemsFromNearbyFurnace** - Get smelted items from furnace ### Inventory Management - **openInventory** - Open the bot's inventory - **equipItem** - Equip armor, tools, or weapons - **dropItem** - Drop items from inventory - **giveItemToSomeone** - Give items to another player ### Building & Farming - **placeItemNearYou** - Place blocks near the bot - **prepareLandForFarming** - Prepare land for farming - **useItemOnBlockOrEntity** - Use items on blocks or entities ### Survival - **eatFood** - Eat food to restore hunger - **rest** - Rest to regain health - **sleepInNearbyBed** - Find and sleep in a bed ### Storage - **openNearbyChest** - Open a nearby chest ### Fun - **dance** - Make the bot dance ### Vision - **lookAround** - Look around and observe the environment ### Communication - **readChat** - Read recent chat messages from the server - **sendChat** - Send chat messages or commands to the server ### Building - **buildSomething** - Build structures using Minecraft commands (requires cheats/operator permissions). Supports both static command arrays and dynamic JavaScript code. - **buildPixelArt** - Build pixel art from an image in Minecraft (requires cheats/operator permissions). Converts an image to pixel art using colored blocks. Maximum size is 256x256 blocks. ## API Example When integrated with an MCP client, you can control the bot like this: ```javascript // First, spawn a bot await client.callTool('joinGame', { username: 'MyBot' }); // Make the bot mine some wood await client.callTool('mineResource', { name: 'oak_log', count: 10 }); // Craft wooden planks await client.callTool('craftItems', { item: 'oak_planks', count: 40 }); // Navigate to coordinates await client.callTool('goToKnownLocation', { x: 100, y: 64, z: 200 }); // Build a structure using commands (requires cheats) - Script mode await client.callTool('buildSomething', { buildScript: [ { command: "fill", x1: 0, y1: 64, z1: 0, x2: 10, y2: 64, z2: 10, block: "stone" }, { command: "fill", x1: 1, y1: 65, z1: 1, x2: 9, y2: 68, z2: 9, block: "oak_planks" }, { command: "setblock", x: 5, y: 65, z: 1, block: "oak_door" } ] }); // Build dynamically with JavaScript (requires cheats) - Code mode await client.callTool('buildSomething', { code: ` // Build a pyramid centered on the bot const size = 10; for (let y = 0; y < size; y++) { const level = size - y; fill(pos.x - level, pos.y + y, pos.z - level, pos.x + level, pos.y + y, pos.z + level, 'sandstone'); await wait(5); // Small delay between levels } log('Pyramid complete!'); ` }); // Build pixel art from an image (requires cheats) await client.callTool('buildPixelArt', { imagePath: 'https://example.com/logo.png', width: 64, height: 64, x: 0, y: 80, z: 100, facing: 'north' }); // Read recent chat messages await client.callTool('readChat', { count: 30, timeLimit: 300, // Last 5 minutes filterType: 'chat' // Only player messages }); // Send a chat message await client.callTool('sendChat', { message: 'Hello everyone! I am a bot.' }); // Send a command await client.callTool('sendChat', { message: '/time set day' }); // Send a whisper await client.callTool('sendChat', { message: '/msg Steve I can help you build!', delay: 1000 // Wait 1 second before sending }); ``` ## Architecture The MCP server: - Uses stdio transport for communication with AI clients - Dynamically loads skills from the verified skills directory - Manages multiple bot instances (currently uses the first bot for all operations) - Provides a unified interface for all bot actions ## Requirements - Node.js >= 18.0.0 - A Minecraft server (Java Edition) to connect to - An MCP-compatible client (like Claude Desktop) ## Troubleshooting ### "Skill implementation not found" Error The MCP server needs to be run from the cloned repository with built skills. Make sure you: 1. Cloned the full repository 2. Ran `npm install` in the minecraft-client directory 3. Ran `npm run build` in the minecraft-client directory 4. Are running the MCP server from the correct directory ### Bot won't connect - Ensure your Minecraft server is running and accessible - Check that the port and host are correct - Verify the server allows the Minecraft version the bot uses ### Skills not working - Make sure the bot has spawned successfully before using skills - Some skills require specific items or conditions - Check the bot's console output for error messages ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License MIT - see LICENSE file for details ## Support For issues and feature requests, please use the [GitHub issue tracker](https://github.com/FundamentalLabs/minecraft-mcp/issues). ### Testing To test with the Anthropic MPC inspector 'npx @modelcontextprotocol/inspector node ./dist/mcp-server.js'