Server data from the Official MCP Registry
Control a Mineflayer Minecraft bot with 120+ MCP tools: move, mine, craft, fight, build, and see.
Control a Mineflayer Minecraft bot with 120+ MCP tools: move, mine, craft, fight, build, and see.
Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 1 issue found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Set these up before or after installing:
Environment variable: MCP_DEFAULT_HOST
Environment variable: MCP_DEFAULT_USERNAME
Environment variable: MCP_DEFAULT_AUTH
Environment variable: MCP_DISABLE_GROUPS
Environment variable: MCP_READ_ONLY
Environment variable: MCP_ALLOWED_HOSTS
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-g0osey99-awesome-mineflayer-mcp": {
"env": {
"MCP_READ_ONLY": "your-mcp-read-only-here",
"MCP_DEFAULT_AUTH": "your-mcp-default-auth-here",
"MCP_DEFAULT_HOST": "your-mcp-default-host-here",
"MCP_ALLOWED_HOSTS": "your-mcp-allowed-hosts-here",
"MCP_DISABLE_GROUPS": "your-mcp-disable-groups-here",
"MCP_DEFAULT_USERNAME": "your-mcp-default-username-here"
},
"args": [
"-y",
"awesome-mineflayer-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
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.
auth: "microsoft").| 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.
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.
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.
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.
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.
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).
| 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. |
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
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.goto, dig, collect_block, craft_item, pvp_attack, chat, …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.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.
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).Full generated reference (every tool, prompt, resource):
docs/TOOLS.md.
Group keys (for MCP_DISABLE_GROUPS) are shown in brackets.
[lifecycle] — connect_bot, connect_default, disconnect_bot, reconnect_bot, respawn, get_connection_status, get_default_account[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] (read-only) — get_block_at, find_blocks, get_cursor_target, get_blocks_in_region, wait_for_chunks_to_load[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_at, look, look_at_entity[digging] — dig, place_block, activate_block, activate_entity, swing_arm[combat] — pvp_attack, attack_entity, pvp_stop, pvp_configure[inventory] — equip_item, unequip_item, toss_item, set_quickbar_slot, consume, activate_item, click_window, move_slot_item, transfer_items[containers] — open_container, read_open_container, container_deposit, container_withdraw, close_window[furnace] — open_furnace, furnace_action, furnace_status, smelt_item[enchanting] — enchant_item, anvil_combine[villager] — open_villager, trade_with_villager[crafting] — list_recipes, craft_item[gathering] — collect_block, cancel_collect, set_collect_config[tool] — equip_tool_for_block, set_tool_chest_locations, get_best_tool[survival] — autoeat_set_enabled, autoeat_configure, autoeat_eat, autoeat_cancel, autoeat_preview, armor_equip_all[beds] — sleep, wake[vehicles] — mount_entity, dismount, steer_vehicle[fishing] — fish, cancel_fish, write_book, update_sign[chat] — chat, whisper, run_command, tab_complete, register_chat_pattern, remove_chat_pattern, wait_for_message[settings] — set_settings[creative] — creative_set_inventory_slot, creative_clear_inventory, creative_fly, creative_fly_to[vision] — get_screenshot (real first-person textured game render), render_map (dependency-free schematic map) — see Vision[waypoints] — set_waypoint, list_waypoints, delete_waypoint, goto_waypoint (persisted across restarts)[build] — clear_region, dig_tunnel, dig_staircase, fill_region (cancellable, multi-block)[events] — get_events, cancel_task[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.
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.
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 renderCaptures 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 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:
npx playwright install chromium once.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 schematicA 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.
Sensible defaults that matter once an agent drives the bot autonomously (especially with a default account):
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.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.MCP_READ_ONLY=true registers only observation tools (plus connection management) — look-but-don't-touch.MCP_CHAT_MIN_INTERVAL_MS spaces outbound chat/commands to avoid spam-kicks.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 slotworld://entities — up to 50 nearest tracked entitiesworld://players — server rosterbot://events — tail of recent eventsbot://waypoints — saved named waypointsPlus parameterized resource templates for on-demand lookups: block://{x}/{y}/{z} and entity://{id}.
Game events are delivered two ways:
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.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.
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.
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 for how to add a tool/group and run a local test server.
Pushing a v* tag publishes to npm, GitHub Container Registry (Docker), the MCP Registry, and updates Smithery — all via .github/workflows/ci.yml. npm version keeps package.json, src/config.ts, and server.json in sync.
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. The published npm package ships only dist/, README.md, LICENSE, and NOTICE (see the files field).
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 — 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.
A Dockerfile is included for headless/autonomous deployments (configure a default account via MCP_DEFAULT_*):
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.)
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).msa_code event); use profilesFolder to cache it.MIT
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.