Minecraft Dedalus MCP Server

Minecraft Dedalus MCP

LAN-oriented Minecraft MCP stack: Python MCP server + Node Mineflayer bridge. Control a bot via the Dedalus agent or in-game chat as natural language commands.

New in v2: Skill library, multi-step planning, persistent world memory, freeform building from natural language, smelting/furnace automation, error recovery with retry, and a creative/survival mode toggle.

Quick start (one command)

Get everything running and command the bot from in-game chat:

1. Open Minecraft Java Edition, start a world, and click Open to LAN. Note the port (e.g. 61246).

2. Expose your MCP server so the cloud agent can reach it (required for chat commands):

   ngrok http 8000
   

   Copy the https://... URL (e.g. https://abc123.ngrok.io).

3. Run the one-command launcher (bridge + MCP server + join game + chat agent):

   export DEDALUS_API_KEY=your_key_here
   uv run python run_live_chat.py --join-host 192.168.68.70 --join-port 61246
   

   Use your machine's LAN IP for --join-host (or 127.0.0.1 if the world is on this machine). Use the port shown in-game for --join-port. Put MINECRAFT_PORT and MINECRAFT_HOST in .env to avoid passing --join-* each time. Add --auth offline to skip the Microsoft login (recommended for LAN worlds).

4. In Minecraft chat, type natural language commands. Examples:

   • mine 10 dirt
   • go to the tree
   • build a 5x5 house with oak planks
   • attack the zombie
   • switch to creative mode and give me 64 diamonds
   • create a plan to get iron tools

What this project is

• Python MCP server – Exposes 60+ Minecraft bot actions as MCP tools (move, mine, place, attack, craft, chat, plan, remember, build, smelt, and more). Built on dedalus_mcp.
• Node bridge – Connects to a real Minecraft (Java) client via Mineflayer. Handles pathfinding (including breaking/placing blocks in the way), digging, placing, combat, inventory, smelting, and slash commands.
• Simulation mode – Test the stack without a live game (simulated world and tools).
• Skill library – Save and reuse multi-step tool sequences (Voyager-inspired).
• Multi-step planner – Decompose goals into checkpointed execution plans.
• World memory – Persistent storage of locations, resources, and structures across sessions.
• Creative/Survival modes – Creative mode unlocks teleport, give, fill, summon, time, weather. Survival mode keeps legit pathfinding and resource gathering.
• Freeform building – Describe structures in natural language (house, tower, bridge, farm, stairs, fence, pool, platform, pillar).
• Error recovery – Automatic retries with alternative positions and resources when tools fail.
• Autonomous survival mode – Say "start autonomous" in chat and the bot plays the game on its own (inspect → plan → execute → learn). Say "stop" to return to command mode.

Requirements

• Python 3.10+ (e.g. via uv)
• Node 20+, npm 10+
• Minecraft Java Edition for real LAN play (world opened to LAN, or a server)
• Dedalus API key for the agent (DEDALUS_API_KEY in .env or environment)
• ngrok (or similar) if you want the cloud agent to respond to in-game chat

Setup

uv sync --extra dev
npm --prefix bridge install

Copy the example env file and fill in your values:

cp .env.example .env
# Edit .env: set DEDALUS_API_KEY, MINECRAFT_PORT (e.g. your LAN port), etc.

Environment variables (`.env` format)

Ways to run

1. One command: bridge + MCP + join + chat agent

export DEDALUS_API_KEY=your_key_here
uv run python run_live_chat.py --join-host YOUR_LAN_IP --join-port LAN_PORT --agent-mcp-url https://YOUR_NGROK_URL/mcp

2. Manual: bridge + MCP server in separate terminals

Terminal 1 – Bridge

npm --prefix bridge run start -- --listen-host 0.0.0.0 --listen-port 8787

Terminal 2 – MCP server