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)
npx --y -- @fundamentallabs/minecraft-mcp
Via npm (Recommended)
npm install -g @fundamentallabs/minecraft-mcp
From Source
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:
# 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
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)
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": ["-y", "-- @fundamentallabs/minecraft-mcp"]
}
}
}
If running locally from source:
{
"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:
# 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 usernamehost(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 disconnectdisconnectAll(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:
// 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:
- Cloned the full repository
- Ran
npm installin the minecraft-client directory - Ran
npm run buildin the minecraft-client directory - 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.
Testing
To test with the Anthropic MPC inspector
'npx @modelcontextprotocol/inspector node ./dist/mcp-server.js'