minecraft-mcp

minecraft-mcp

3.5

If you are the rightful owner of minecraft-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Fundamental Labs/Minecraft Client is a library designed for integrating AI agents with Minecraft servers, providing full control over bots and offering a range of pre-built skills for various tasks.

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:

  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.

Testing

To test with the Anthropic MPC inspector

'npx @modelcontextprotocol/inspector node ./dist/mcp-server.js'