awesome-mineflayer-mcp

A production-ready Model Context Protocol server that gives an LLM agent standalone-equivalent control over a Mineflayer Minecraft bot — movement, mining, crafting, inventory, combat, containers, chat, and much more — exposed as 123 strongly-typed tools across 26 groups, plus guided prompts, vision (real first-person screenshots + schematic maps), persistent waypoints, build/dig macros, and dual (poll + push) event streaming, with full bot lifecycle management. Tool results carry both human-readable text and machine-readable structuredContent.

Backed by the Mineflayer ecosystem: mineflayer-pathfinder (A* navigation), mineflayer-pvp (combat), mineflayer-collectblock (gathering), mineflayer-tool (auto tool-select), mineflayer-auto-eat, and mineflayer-armor-manager.

Requirements

• Node.js ≥ 20 (developed on 22.16)
• A Minecraft server to connect to (Java Edition). The bot auto-detects the server version. Don't have one? See Get a server to test against.
• For online-mode servers: a Microsoft account (auth: "microsoft").

Supported versions

A few tools only work on newer versions/features (e.g. elytra_fly, chat signing). On a version mismatch the bot is kicked with an outdated client/server message — pass an explicit version.

Installation

Run it on demand with npx (no install needed):

npx awesome-mineflayer-mcp

…or install it globally:

npm install -g awesome-mineflayer-mcp
awesome-mineflayer-mcp

The server speaks MCP over stdio, so it is normally launched by your MCP client rather than run by hand.

Use with an MCP client

Add it to your client's MCP server configuration. The recommended form uses npx so you always get the latest published build:

Claude Desktop (claude_desktop_config.json), Claude Code, Cursor, or any stdio MCP client:

{
  "mcpServers": {
    "mineflayer": {
      "command": "npx",
      "args": ["-y", "awesome-mineflayer-mcp"],
      "env": {
        "MCP_DISABLE_GROUPS": ""
      }
    }
  }
}

If you installed it globally, use "command": "awesome-mineflayer-mcp" with "args": [] instead.

Get a Minecraft server to test against

If you don't already have a server, spin up a throwaway offline-mode one with Docker (no account needed):

# from a clone of this repo:
docker compose up -d        # offline 1.20.4 server on localhost:25565
docker compose logs -f      # wait for "Done (…)! For help, type "help""

…or a one-liner without the repo:

docker run -d --name mc -p 25565:25565 -e EULA=TRUE -e ONLINE_MODE=FALSE -e VERSION=1.20.4 itzg/minecraft-server

Then connect: connect_bot { host: "localhost", username: "DevBot", auth: "offline" }. Tear it down with docker compose down -v (or docker rm -f mc). Don't expose an offline-mode server to the public internet.

Autonomous operation (default account)

For hands-off use, configure a default account so the bot connects automatically on startup — no connect_bot call required. Run the interactive setup:

npx awesome-mineflayer-mcp setup

It asks for the server host/port, an offline or Microsoft account, and whether to auto-connect on startup, then writes ~/.awesome-mineflayer-mcp/config.json (no password is stored). For a Microsoft account it runs the device-code sign-in once and caches the token under profilesFolder, so later startups need no prompt.

On startup the server auto-connects the configured account (verify with get_connection_status). The agent can also call connect_default to (re)connect it or get_default_account to inspect it.

Configure without the wizard (env vars)

You can set the default account entirely from your MCP client config — handy for headless deploys. Environment variables override the config file:

{
  "mcpServers": {
    "mineflayer": {
      "command": "npx",
      "args": ["-y", "awesome-mineflayer-mcp"],
      "env": {
        "MCP_DEFAULT_HOST": "play.example.net",
        "MCP_DEFAULT_USERNAME": "MyBot",
        "MCP_DEFAULT_AUTH": "offline",
        "MCP_AUTO_CONNECT": "true"
      }
    }
  }
}

For Microsoft auth in a headless setup, run setup once locally first (or point MCP_PROFILES_FOLDER at a directory with a pre-cached token).

Configuration (environment variables)

Example — disable rarely-used groups:

MCP_DISABLE_GROUPS=creative,villager,enchanting,settings

Quick start (tool flow)

1. connect_bot { host, username, auth } — connect (resolves once the bot spawns). Skip this if you configured a default account — the bot auto-connects on startup; just check get_connection_status.
2. Act: goto, dig, collect_block, craft_item, pvp_attack, chat, …
3. Observe: call get_observation for a one-shot snapshot (vitals, position, inventory, nearby entities, new events) — pass the returned events.nextSince back each tick. Or compose get_state / get_inventory / list_entities / get_events, or subscribe to the bot://* resources.
4. disconnect_bot when done.

New to the server? Use the getting_started prompt (see Prompts) for an in-context walkthrough.

Block / item / entity arguments accept human names ("iron_ore", "diamond_pickaxe", "zombie"); unknown names return fuzzy suggestions.

Authentication

• auth: "offline" (default) — offline-mode servers; username is the in-game name.
• auth: "microsoft" — username is the account email. A device-code prompt is emitted as an msa_code event / log notification. Set profilesFolder to cache the token so subsequent runs skip the prompt, or pass a cached accessToken. Tip: run npx awesome-mineflayer-mcp setup once to do the device-code sign-in and cache the token, then the server connects autonomously (see Autonomous operation).

Tool catalog (123 tools, 26 groups)

Full generated reference (every tool, prompt, resource): docs/TOOLS.md.

Group keys (for MCP_DISABLE_GROUPS) are shown in brackets.