Content
# awesome-mineflayer-mcp
[](https://www.npmjs.com/package/awesome-mineflayer-mcp)
[](https://nodejs.org)
[](./LICENSE)
A production-ready [Model Context Protocol](https://modelcontextprotocol.io) server that gives an LLM agent **standalone-equivalent control** over a [Mineflayer](https://github.com/PrismarineJS/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](#get-a-minecraft-server-to-test-against).
- For online-mode servers: a Microsoft account (`auth: "microsoft"`).
### Supported versions
| | Supported |
|---|---|
| Minecraft (Java) | the range supported by the bundled `mineflayer` 4.37 / `minecraft-data` (roughly **1.8 → 1.21.x**); version is auto-detected, or pass `version` explicitly |
| Node.js | **20, 22** (LTS) |
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):
```bash
npx awesome-mineflayer-mcp
```
…or install it globally:
```bash
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:
```json
{
"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):
```bash
# 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:
```bash
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:
```bash
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:
```json
{
"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)
| Variable | Default | Purpose |
|---|---|---|
| `MCP_DISABLE_GROUPS` | _(none)_ | Comma-separated tool-group keys to disable (see catalog). Trim the surface for clients that struggle with a large tool list. |
| `MCP_CHARACTER_LIMIT` | `25000` | Max characters returned by any single tool call (truncated with a marker). |
| `MCP_EVENT_BUFFER` | `1000` | Size of the in-memory event ring buffer. |
| `MCP_THROTTLE_MS` | `250` | Minimum spacing between pushed resource-update / log notifications. |
| `MCP_PROXIMITY_RADIUS` | `32` | Radius (blocks) for proximity-filtered events (entity spawns, sounds). |
| `MCP_ACTION_TIMEOUT_MS` | `60000` | Default timeout for long actions when the caller omits one. |
| `MCP_DEFAULT_HOST` / `MCP_DEFAULT_PORT` | — | Default server to auto-connect on startup. |
| `MCP_DEFAULT_USERNAME` | — | Default account name (offline) or email (microsoft). |
| `MCP_DEFAULT_AUTH` | `offline` | Default auth mode: `offline` or `microsoft`. |
| `MCP_DEFAULT_VERSION` | auto | Force a protocol version for the default account. |
| `MCP_DEFAULT_AUTO_RECONNECT` | `true` | Auto-reconnect the default account on disconnect. |
| `MCP_AUTO_CONNECT` | `true`† | Auto-connect the default on startup († when a default is configured). |
| `MCP_PROFILES_FOLDER` | `<home>/profiles` | Microsoft auth token-cache directory. |
| `AWESOME_MINEFLAYER_MCP_HOME` | `~/.awesome-mineflayer-mcp` | Config + token-cache directory. |
| `MCP_READ_ONLY` | `false` | Observe-only mode: register only read-only tools (+ lifecycle). See [Safety](#safety--guardrails). |
| `MCP_COMMAND_DENY` | _(admin verbs)_ | Slash commands `run_command` blocks. Setting it **replaces** the default; set empty to allow all. |
| `MCP_COMMAND_ALLOW` | _(none)_ | If set, a strict allow-list: only these commands run (deny list ignored). |
| `MCP_ALLOWED_HOSTS` | _(any)_ | Comma-separated allow-list of hosts the bot may connect to. |
| `MCP_CHAT_MIN_INTERVAL_MS` | `0` | Minimum spacing between outbound chat/whisper/command sends (anti-spam). |
| `MCP_ENABLE_RAW` | `false` | Enable the advanced/unsafe `raw` protocol tool group (direct packet send/subscribe). |
| `MCP_SCREENSHOT_WIDTH` / `_HEIGHT` | `800` / `450` | Default `get_screenshot` image size (px). |
| `MCP_SCREENSHOT_LOAD_MS` | `2500` | How long to let the world render before capturing a screenshot. |
| `MCP_VIEW_DISTANCE` | `4` | Chunk render distance for screenshots. |
| `MCP_SCREENSHOT_BROWSER_CHANNEL` | _(auto)_ | Browser channel for screenshots (`chrome`, `msedge`, `chromium`). |
| `MCP_SCREENSHOT_EXECUTABLE_PATH` | _(none)_ | Explicit browser executable path for screenshots (overrides channel). |
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](#autonomous-operation-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](#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](#autonomous-operation-default-account)).
---
## Tool catalog (123 tools, 26 groups)
> Full generated reference (every tool, prompt, resource): [`docs/TOOLS.md`](docs/TOOLS.md).
Group keys (for `MCP_DISABLE_GROUPS`) are shown in brackets.
- **Lifecycle** `[lifecycle]` — `connect_bot`, `connect_default`, `disconnect_bot`, `reconnect_bot`, `respawn`, `get_connection_status`, `get_default_account`
- **State & inspection** `[state]` (read-only) — `get_observation` (one-call snapshot for an agent's observe loop), `get_state`, `get_inventory`, `list_players`, `list_entities`, `find_nearest_entity`, `get_entity_details`, `get_scoreboards`, `get_teams`, `get_boss_bars`, `get_control_states`, `get_chat_patterns`, `support_feature`, `pathfinder_status`, `get_settings`, `get_physics`, `get_loaded_plugins`
- **World queries** `[world]` (read-only) — `get_block_at`, `find_blocks`, `get_cursor_target`, `get_blocks_in_region`, `wait_for_chunks_to_load`
- **Movement & pathfinding** `[movement]` — `goto`, `set_goal`, `flee_from`, `follow_entity`, `stop_pathfinding`, `get_path_to`, `configure_movements`, `configure_pathfinder`, `set_control_state`, `clear_control_states`, `elytra_fly`, `wait_for_ticks`, `set_physics_enabled`
- **Look** `[look]` — `look_at`, `look`, `look_at_entity`
- **Digging & building** `[digging]` — `dig`, `place_block`, `activate_block`, `activate_entity`, `swing_arm`
- **Combat** `[combat]` — `pvp_attack`, `attack_entity`, `pvp_stop`, `pvp_configure`
- **Inventory & items** `[inventory]` — `equip_item`, `unequip_item`, `toss_item`, `set_quickbar_slot`, `consume`, `activate_item`, `click_window`, `move_slot_item`, `transfer_items`
- **Containers** `[containers]` — `open_container`, `read_open_container`, `container_deposit`, `container_withdraw`, `close_window`
- **Furnace / smelting** `[furnace]` — `open_furnace`, `furnace_action`, `furnace_status`, `smelt_item`
- **Enchanting & anvil** `[enchanting]` — `enchant_item`, `anvil_combine`
- **Villager trading** `[villager]` — `open_villager`, `trade_with_villager`
- **Crafting** `[crafting]` — `list_recipes`, `craft_item`
- **Block gathering** `[gathering]` — `collect_block`, `cancel_collect`, `set_collect_config`
- **Tool auto-select** `[tool]` — `equip_tool_for_block`, `set_tool_chest_locations`, `get_best_tool`
- **Survival automation** `[survival]` — `autoeat_set_enabled`, `autoeat_configure`, `autoeat_eat`, `autoeat_cancel`, `autoeat_preview`, `armor_equip_all`
- **Beds & sleep** `[beds]` — `sleep`, `wake`
- **Vehicles** `[vehicles]` — `mount_entity`, `dismount`, `steer_vehicle`
- **Fishing, books & signs** `[fishing]` — `fish`, `cancel_fish`, `write_book`, `update_sign`
- **Chat & communication** `[chat]` — `chat`, `whisper`, `run_command`, `tab_complete`, `register_chat_pattern`, `remove_chat_pattern`, `wait_for_message`
- **Settings** `[settings]` — `set_settings`
- **Creative mode** `[creative]` — `creative_set_inventory_slot`, `creative_clear_inventory`, `creative_fly`, `creative_fly_to`
- **Vision** `[vision]` — `get_screenshot` (real first-person textured game render), `render_map` (dependency-free schematic map) — see [Vision](#vision--let-the-agent-see)
- **Waypoints** `[waypoints]` — `set_waypoint`, `list_waypoints`, `delete_waypoint`, `goto_waypoint` (persisted across restarts)
- **Build & dig macros** `[build]` — `clear_region`, `dig_tunnel`, `dig_staircase`, `fill_region` (cancellable, multi-block)
- **Events & telemetry** `[events]` — `get_events`, `cancel_task`
- **Raw protocol** `[raw]` — `send_packet`, `subscribe_packet`, `list_packet_subscriptions` (advanced/unsafe; **off unless `MCP_ENABLE_RAW=true`**)
Long-running actions (`goto`, `dig`, `collect_block`, `pvp_attack`, `fish`, `smelt_item`, `craft_item`) are mutually exclusive and cancellable — start a new movement/combat action to supersede the prior one, or call `stop_pathfinding` / `pvp_stop` / `cancel_collect` / `cancel_fish` / `cancel_task`.
## Prompts
The server exposes **guided, parameterized workflows** as MCP prompts — clients surface them as slash-commands / templates. They teach an agent how to chain the right tools for a goal:
- **`getting_started`** — orientation: connect → observe → act → recover.
- **`gather_wood`** `{ count?, logType? }` — find trees and collect logs.
- **`mine_to_diamonds`** `{ targetY? }` — descend safely and branch-mine.
- **`build_shelter`** `{ material? }` — enclose a safe space before nightfall.
- **`find_and_smelt`** `{ input, fuel? }` — mine/gather an input and smelt it.
- **`follow_and_defend`** `{ player }` — follow a player and fight off hostiles.
Block/item arguments offer name autocompletion drawn from the connected world.
## Vision — let the agent *see*
Two complementary tools return PNG images as MCP image content, so a vision-capable model (and a human) can look at the world instead of reconstructing it from JSON.
### `get_screenshot` — a real game render
Captures an **actual textured Minecraft render** of what the bot sees — first-person from its eyes (default) or a third-person orbit — exactly like an in-game screenshot. Under the hood, [`prismarine-viewer`](https://github.com/PrismarineJS/prismarine-viewer) renders the real world (client-side WebGL) and a headless browser screenshots it. Args: `width`, `height`, `firstPerson`, `waitMs`, `viewDistance`.
**Setup (one-time).** The renderer deps ship as **optional** packages (installed by default with `npm install`). All you also need is a browser:
- Already have **Google Chrome or Microsoft Edge**? Nothing to do — it's used automatically.
- Otherwise run **`npx playwright install chromium`** once.
- Headless servers: install Chrome/Chromium, or set `MCP_SCREENSHOT_EXECUTABLE_PATH` / `MCP_SCREENSHOT_BROWSER_CHANNEL`.
If the deps/browser aren't available, `get_screenshot` returns a clear `UNSUPPORTED` error with these steps — the rest of the server is unaffected. The renderer packages are pure-JS (no native build), but if you want the leanest possible install and don't need screenshots, use `npm install --omit=optional`.
### `render_map` — a dependency-free schematic
A lightweight colored top-down map (or `mode:"slice"` cross-section) drawn from block data with a **built-in PNG encoder** (no extra deps at all). Good as a minimap/overview or when the screenshot extras aren't installed. North (−Z) is up; bot = white dot with a facing tick; players cyan, hostiles red, passives yellow, items grey; includes a block legend.
## Safety & guardrails
Sensible defaults that matter once an agent drives the bot autonomously (especially with a [default account](#autonomous-operation-default-account)):
- **Command policy.** `run_command` blocks server-administration verbs by default (`op`, `deop`, `ban`, `kick`, `stop`, `whitelist`, and the `execute`/`function`/`schedule` wrappers, …). Ordinary gameplay commands (`/tp`, `/time`, `/give`, …) are allowed. Override with `MCP_COMMAND_DENY` (replaces the default; empty = allow all) or lock down with `MCP_COMMAND_ALLOW` (strict allow-list). This is **best-effort defense-in-depth**, not a hard boundary — it gates on the first command verb, and a bot with operator permissions could still find a way around it. For untrusted/autonomous deployments, prefer `MCP_COMMAND_ALLOW`, `MCP_READ_ONLY`, and not granting the bot's account operator rights. **Note:** incoming player chat is delivered to your agent as events — treat it as untrusted input.
- **Host allow-list.** `MCP_ALLOWED_HOSTS` restricts which servers `connect_bot` / `reconnect_bot` may join, so an agent can't repoint the bot (and its cached token) at an arbitrary address.
- **Read-only mode.** `MCP_READ_ONLY=true` registers only observation tools (plus connection management) — look-but-don't-touch.
- **Rate limiting.** `MCP_CHAT_MIN_INTERVAL_MS` spaces outbound chat/commands to avoid spam-kicks.
- **No secret leakage.** Passwords / access tokens are never stored on disk and are redacted from connection-error messages.
## Resources
Subscribe-capable JSON resources for clients that support resource subscriptions:
- `bot://state` — live self snapshot (position, vitals, gamemode, time, weather, held item, control states)
- `bot://inventory` — items, armor, off-hand, held slot
- `world://entities` — up to 50 nearest tracked entities
- `world://players` — server roster
- `bot://events` — tail of recent events
- `bot://waypoints` — saved named waypoints
Plus parameterized **resource templates** for on-demand lookups: `block://{x}/{y}/{z}` and `entity://{id}`.
## Events
Game events are delivered two ways:
- **Pull:** `get_events({ since, types, limit })` drains a ring buffer; pass the returned `nextSince` to read only new events. `dropped: true` signals the buffer overflowed since your `since`.
- **Push:** subscribed resources emit throttled `notifications/resources/updated`; notable lines (chat, death, kick, error, msa_code) are forwarded via `sendLoggingMessage`.
High-frequency observations (movement, per-tick updates, block/entity updates, time) are intentionally **not** buffered — read them on demand via `get_state` and the read-only tools.
## Development (from source)
```bash
git clone https://github.com/G0Osey99/awesome-mineflayer-mcp.git
cd awesome-mineflayer-mcp
npm install
npm run build # tsc -> dist/
npm run typecheck # tsc --noEmit
npm test # vitest (unit tests for the pure logic)
npm run dev # tsx src/index.ts (run from source, no build step)
```
Architecture and the full design rationale: [`docs/superpowers/specs/2026-06-28-mineflayer-mcp-server-design.md`](docs/superpowers/specs/2026-06-28-mineflayer-mcp-server-design.md).
```
src/
index.ts entry (stdio transport, graceful shutdown, crash guards)
server.ts builds the McpServer, registers tool groups + resources + prompts
config.ts env + constants + safety policy (groups, read-only, command/host allow-lists)
bot/ manager (lifecycle FSM), plugins, events, wire-events, state, windows, action-locks
tools/ one module per tool group (+ registry.ts)
prompts/ guided multi-tool workflows
resources/ MCP resources + push notifications
util/ errors, format, result, resolve (name→id + fuzzy), serialize, async, redact
schemas/ shared Zod fragments
```
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to add a tool/group and run a local test server.
## Publishing (maintainers)
Pushing a `v*` tag publishes to **npm**, **GitHub Container Registry** (Docker), the **MCP Registry**, and updates **Smithery** — all via [`.github/workflows/ci.yml`](.github/workflows/ci.yml). `npm version` keeps `package.json`, `src/config.ts`, and `server.json` in sync.
```bash
npm version minor # bumps + syncs versions, commits, and tags
git push --follow-tags # triggers the release jobs
```
Full one-time setup and the step-by-step release checklist are in [`RELEASE.md`](RELEASE.md). The published npm package ships only `dist/`, `README.md`, `LICENSE`, and `NOTICE` (see the `files` field).
## Troubleshooting
Connection failures now return a **specific error code and suggestions** (not an opaque `INTERNAL`). Common cases:
| Symptom / error | Likely cause | Fix |
|---|---|---|
| `CONNECT_REFUSED` (ECONNREFUSED) | Wrong host/port, or server not running | Check `host`/`port`; confirm the server has finished starting (default port 25565). |
| `CONNECT_REFUSED` (ENOTFOUND) | Hostname doesn't resolve | Double-check the server address. |
| `ONLINE_MODE` / "unverified username" | Server is online-mode; bot used offline auth | Use `auth: "microsoft"`, or set `online-mode=false` on the server. |
| `VERSION_MISMATCH` / "outdated client/server" | Auto-detected version is wrong | Pass an explicit `version` (e.g. `"1.20.4"`). |
| Chat rejected / "secure profile" | Server requires signed chat | Connect with `disableChatSigning: true`. |
| `AUTH_FAILED` | Stale/invalid Microsoft token | Re-run `npx awesome-mineflayer-mcp setup`, or clear the `profilesFolder` cache and sign in again. |
| `FORBIDDEN` on `run_command` | Command blocked by policy | See [Safety](#safety--guardrails) — adjust `MCP_COMMAND_DENY` / `MCP_COMMAND_ALLOW`. |
| `FORBIDDEN` on `connect_bot` | Host not in allow-list | Add it to `MCP_ALLOWED_HOSTS` (or unset to allow any). |
| `NO_PATH` | Pathfinder can't reach the goal | Move closer, clear obstacles, or relax `configure_movements`. |
| Microsoft device-code prompt | First-time MSA sign-in | Visit the URL from the `msa_code` event; set `profilesFolder` to cache it. |
First-run sign-in for Microsoft auth is interactive once — run `npx awesome-mineflayer-mcp setup` to do it and cache the token.
## Docker
A `Dockerfile` is included for headless/autonomous deployments (configure a default account via `MCP_DEFAULT_*`):
```bash
docker build -t awesome-mineflayer-mcp .
```
Mount a volume at `/root/.awesome-mineflayer-mcp` to persist the config and Microsoft token cache. (The server speaks MCP over stdio, so a container is most useful for autonomous default-account runs rather than for a client to spawn.)
## Limitations
- **One bot per server process** (single-session by design).
- **Evaluations require a seeded world.** A live Minecraft world is not deterministic, so the evaluation set in `eval/` targets a documented seeded fixture (see `eval/fixture.md`); it cannot be verified against an arbitrary live server.
- `cancel_fish` is best-effort (Mineflayer exposes no first-class fishing abort).
- Microsoft auth's first run needs an interactive device code (surfaced as an `msa_code` event); use `profilesFolder` to cache it.
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available