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

// 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 install in the minecraft-client directory
Ran npm run build in 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'