Cobble MCP 🧱🤖

Created and maintained by Brian Mwirigi, Cobble MCP transforms a standard Minecraft bot into a sentient, survival-ready AI companion.

Cobble MCP operates on a dual-engine architecture:

1. Full Model Context Protocol (MCP) Server: Directly controls Minecraft through Claude Desktop, Antigravity IDE, Cursor, or any MCP-compatible AI client.

2. Autonomous Gemini 2.5 Companion Brain: A built-in real-time perception engine with 360-degree spatial awareness, survival reflex watchdogs, combat bodyguard instincts, and voice/chat interaction.

🌟 Key Features

🛡️ Autonomous Bodyguard & Threat Radar

• 22-Meter Dual Radar: Continuously scans the environment around both the bot and the player.

• Auto-Engage Combat: The moment a threat enters the perimeter, the bot draws its weapon, pathfinds dynamically toward the mob, and strikes until defeated.

• Boss & Flying Combat: Extended hit reach and aerial pursuit for Ender Dragons, Withers, Wardens, Endermen, and all standard hostile mobs.

• Auto-Equip Arsenal: Instantly equips best armor (Netherite/Diamond) and highest-damage weapon prior to swinging.

• Seamless Follow Resumption: Automatically gathers dropped loot and runs back to your side the moment combat ends.

🚶 House-Safe Player Escort & Navigation

• Anti-Grief Pathfinder: Configured with canDig = false and allow1by1towers = false so the bot never breaks walls, roofs, or doors when navigating inside player houses.

• Dynamic Tracking: Follows moving players smoothly with door-opening and parkour abilities.

🏗️ Architectural Survey & Multi-Phase Construction

• Site Survey Engine (survey-site): Scans topography, elevation profiles, ground slope, clearance volume, and obstacle densities before building.

• Voxel Construction Engine (build, mc_build): Multi-phase bottom-to-top automated construction with material calculations, error recovery, and pause/resume tracking.

• Automated Blueprints: Build emergency bunkers, domes, shelters, houses, walls, and towers on demand.

⛏️ Smart Gathering & Inventory Sharing

• Heuristic Mining (gather-resource): Automatically selects the optimal harvest tool (axes for logs/wood, pickaxes for stone/ores, shovels for dirt/sand).

• Item Gifting (drop-item): Tossa weapons, armor, or mined materials directly to the player at any time.

🍲 Survival & Reflex Watchdogs

• Auto-Eat Watchdog: Monitors hunger and health, proactively consuming high-saturation food (Golden Carrots, Cooked Beef, Enchanted Apples).

• Hazard Avoidance: Automatically douses fire by jumping into nearby water, sleeps through the night in nearby beds, or digs emergency survival shelters when trapped.

📋 Available MCP Tools (30+)

🚀 Getting Started

Prerequisites

• Node.js: >= 20.10.0

• Git

• Minecraft Java Edition: Tested with version 1.21.x

Installation

# Clone the repository
git clone https://github.com/brian-mwirigi/cobble-mcp.git
cd cobble-mcp

# Install dependencies
npm install

# Build the project
npm run build

Setup Environment

Create a .env file in the project root:

# Optional: Required if using autonomous Gemini in-game companion chat
GEMINI_API_KEY=your_gemini_api_key_here

🤖 Using with Claude Desktop

Open your Claude Desktop configuration file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the cobble-mcp server:

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "C:/path/to/cobble-mcp/dist/main.js",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "ClaudeBot"
      ]
    }
  }
}

🎮 Running Minecraft

1. Launch Minecraft Java Edition 1.21.x.

2. Start a singleplayer world and open it to LAN (ESC $\rightarrow$ Open to LAN), or join your server.

3. Start Claude Desktop or run the standalone companion:

npm start -- --host localhost --port 25565 --username AntigravityBot

🧪 Testing

Cobble MCP comes with a comprehensive suite of 140+ unit and integration tests:

npm test

👤 Author

Brian Mwirigi

• GitHub: @brian-mwirigi

• Repository: brian-mwirigi/cobble-mcp

📄 License

This project is licensed under the MIT License.