Fundamental Labs/Minecraft Client

Control Minecraft bots with AI integration. Requires a Java Edition Minecraft server.

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.

npx --y -- @fundamentallabs/minecraft-mcp

npm install -g @fundamentallabs/minecraft-mcp

git clone https://github.com/FundamentalLabs/minecraft-mcp.git cd minecraft-mcp/minecraft-client/mcp-server npm install npm run build

# Start with no defaults (connection specified per bot) minecraft-mcp # Start with default connection settings minecraft-mcp -h play.example.com -p 25565

Options: -p, --port <port> Minecraft server port (default: 25565) -h, --host <host> Minecraft server host (default: localhost) --help Display help

{ "mcpServers": { "minecraft": { "command": "npx", "args": ["-y", "-- @fundamentallabs/minecraft-mcp"] } } }

{ "mcpServers": { "minecraft": { "command": "node", "args": ["/path/to/minecraft-mcp/minecraft-client/mcp-server/dist/mcp-server.js"] } } }

Replace/path/to/minecraft-mcpwith the actual path where you cloned the repository.

The server uses stdio transport and can be integrated with any MCP client:

# Using the MCP inspector for testing cd minecraft-client/mcp-server npx @modelcontextprotocol/inspector node dist/mcp-server.js -- -p 25565

-

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

- goToSomeone- Navigate to another player
- goToKnownLocation- Navigate to specific coordinates
- runAway- Run away from threats
- swimToLand- Swim to nearest land when in water

- attackSomeone- Attack players, mobs, or animals
- hunt- Hunt animals or mobs

- mineResource- Mine specific blocks or resources
- harvestMatureCrops- Harvest mature crops from farmland
- pickupItem- Pick up items from the ground

- 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

- openInventory- Open the bot's inventory
- equipItem- Equip armor, tools, or weapons
- dropItem- Drop items from inventory
- giveItemToSomeone- Give items to another player

- placeItemNearYou- Place blocks near the bot
- prepareLandForFarming- Prepare land for farming
- useItemOnBlockOrEntity- Use items on blocks or entities

- eatFood- Eat food to restore hunger
- rest- Rest to regain health
- sleepInNearbyBed- Find and sleep in a bed

- lookAround- Look around and observe the environment

- readChat- Read recent chat messages from the server
- sendChat- Send chat messages or commands to the server

- 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.

When integrated with an MCP client, you can control the bot like this:

// 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 });

- 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

- Node.js >= 18.0.0
- A Minecraft server (Java Edition) to connect to
- An MCP-compatible client (like Claude Desktop)

"Skill implementation not found" Error

The MCP server needs to be run from the cloned repository with built skills. Make sure you:
- Cloned the full repository
- Rannpm installin the minecraft-client directory
- Rannpm run buildin the minecraft-client directory
- Are running the MCP server from the correct directory

- 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

- 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

Contributions are welcome! Please feel free to submit a Pull Request.

For issues and feature requests, please use theGitHub issue tracker.

A massively multiplayer online game for AI agents -- pilot spaceships, mine, trade, craft, explore, and battle in a galaxy of ~500 systems via MCP.