Prototype · Preview: every server in the official registry, synced every 30 minutes. Sign in with Google to write reviews.Prototype · updated every 30 min
PopNx MCPMCP servers for people who use AI · explained in plain words

Awesome Mineflayer MCP

by G0Osey99version 1.3.2i★ 10iRuns on your computerRepository ↗
Registry nameio.github.G0Osey99/awesome-mineflayer-mcp

How to install

What it does

Control a Mineflayer Minecraft bot with 120+ MCP tools: move, mine, craft, fight, build, and see.

  • Connects Runs on your computer
  • Account or key Needs MCP_DEFAULT_AUTH
  • Category Other

Why it ranks here

Lists are ordered by a usage score (out of 100) built from these parts

Popularity12/80GitHub stars or weekly downloads: the larger counts 60, the smaller 20
Freshness3/12Full marks for a release or code change within 30 days
Still answering0/8The cloud endpoint answered at the last check
Usage score15/100

Quality: Passed 3/3 basic checks (shown, not used for ordering) · Momentum: No data yet (Used only on the Trending tab)

Install

Pick the AI app you use, then copy the settings.

Let your AI install it with one sentence

Please install Awesome Mineflayer MCP. Follow https://mcp.popnx.com/i/g0osey99-awesome-mineflayer-mcp.md, show me the commands and wait for my OK before running them.

Paste it into an AI that can work on your computer (such as Claude Code or Cursor). It reads our steps, shows you the commands and waits for your OK. No key, no sign-up. · See the full text your AI reads

Passed 3/3 checks · Runs on your computer · ✓ Commands checked Nov 14, 2026

First: which AI do you use?

Pick your app and the steps appear below.

Works with Claude, with some setup first

You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone

Let AI install it

Copy this message into a Claude chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Awesome Mineflayer MCP for Claude on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "mcpServers": { "awesome-mineflayer": { "command": "npx", "args": [ "-y", "awesome-mineflayer-mcp" ], "env": { "MCP_DEFAULT_AUTH": "your-value" } } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) For MCP_DEFAULT_AUTH, leave "your-value" in place and tell me to paste the real value myself into the file or the app’s field. Never ask me to type a key in chat. 5) Do what we agreed, then check that the Awesome Mineflayer MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Sign up and create a Awesome Mineflayer MCP key

    Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.

    Open the Awesome Mineflayer MCP site ↗

  3. Open the Claude desktop app’s settings file

    SettingsDeveloperEdit Config

  4. Paste these settings and save the file

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

    Paste the key only into the app’s field, never into a chat or to anyone

  5. Quit Claude and open it again

  6. Try it

    Use Awesome Mineflayer MCP and tell me what you can do for me, then show me one thing

    ✓ If Claude says it is using Awesome Mineflayer MCP or shows a Awesome Mineflayer MCP tool in the answer, you are connected

5 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • MCP_DEFAULT_HOST Server to auto-connect on startup (optional).
  • MCP_DEFAULT_USERNAME In-game name (offline) or account email (microsoft).
  • MCP_DISABLE_GROUPS Comma-separated tool-group keys to disable.
  • MCP_READ_ONLY Observe-only mode (no world-mutating tools).
  • MCP_ALLOWED_HOSTS Comma-separated allow-list of hosts the bot may join.

Descriptions are as written by the maker.

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

ChatGPT cannot connect Awesome Mineflayer MCP yet

Awesome Mineflayer MCP runs on your computer, but ChatGPT can only connect servers that run on the web

What you can do instead

A · Use an app that can connect Awesome Mineflayer MCP

  • You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time) · Only the Claude desktop app (Windows or Mac), not the web or phone
  • You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time)
  • You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time)
  • You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time)

B · Others in Other that work with ChatGPT

Picked from the most used in the same category, only ones that connect by address with no key

Works with Claude Code, with some setup first

You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time)

Let AI install it

Copy this message into a Claude Code chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Awesome Mineflayer MCP for Claude Code on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): claude mcp add --scope user awesome-mineflayer --env MCP_DEFAULT_AUTH=your-value -- npx -y awesome-mineflayer-mcp 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) For MCP_DEFAULT_AUTH, leave "your-value" in place and tell me to paste the real value myself into the file or the app’s field. Never ask me to type a key in chat. 5) Do what we agreed, then check that the Awesome Mineflayer MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Sign up and create a Awesome Mineflayer MCP key

    Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.

    Open the Awesome Mineflayer MCP site ↗

  3. Open Terminal

    Mac: press Command+Space and type Terminal · Windows: open PowerShell

  4. Paste this command and press Enter

    claude mcp add --scope user awesome-mineflayer --env MCP_DEFAULT_AUTH=your-value -- npx -y awesome-mineflayer-mcp

    Replace “your-value” with your key before pressing Enter

    Paste the key only into the app’s field, never into a chat or to anyone

  5. Type /mcp in Claude Code

    You should see Awesome Mineflayer MCP listed as connected

  6. Try it

    Use Awesome Mineflayer MCP and tell me what you can do for me, then show me one thing

    ✓ If Claude Code says it is using Awesome Mineflayer MCP or shows a Awesome Mineflayer MCP tool in the answer, you are connected

5 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • MCP_DEFAULT_HOST Server to auto-connect on startup (optional).
  • MCP_DEFAULT_USERNAME In-game name (offline) or account email (microsoft).
  • MCP_DISABLE_GROUPS Comma-separated tool-group keys to disable.
  • MCP_READ_ONLY Observe-only mode (no world-mutating tools).
  • MCP_ALLOWED_HOSTS Comma-separated allow-list of hosts the bot may join.

Descriptions are as written by the maker.

Menu names checked against Anthropic’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with Cursor, with some setup first

You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time)

Let AI install it

Copy this message into a Cursor chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Awesome Mineflayer MCP for Cursor on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "mcpServers": { "awesome-mineflayer": { "command": "npx", "args": [ "-y", "awesome-mineflayer-mcp" ], "env": { "MCP_DEFAULT_AUTH": "your-value" } } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) For MCP_DEFAULT_AUTH, leave "your-value" in place and tell me to paste the real value myself into the file or the app’s field. Never ask me to type a key in chat. 5) Do what we agreed, then check that the Awesome Mineflayer MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Sign up and create a Awesome Mineflayer MCP key

    Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.

    Open the Awesome Mineflayer MCP site ↗

  3. Click this button to open Cursor

    Open in Cursor

    Cursor asks you to confirm; click Install

  4. Fill in your key

    In the Awesome Mineflayer MCP settings, MCP_DEFAULT_AUTH is empty; add your key and save

    Paste the key only into the app’s field, never into a chat or to anyone

  5. Open the AI chat in Cursor in Agent mode

  6. Try it

    Use Awesome Mineflayer MCP and tell me what you can do for me, then show me one thing

    ✓ If Cursor says it is using Awesome Mineflayer MCP or shows a Awesome Mineflayer MCP tool in the answer, you are connected

5 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • MCP_DEFAULT_HOST Server to auto-connect on startup (optional).
  • MCP_DEFAULT_USERNAME In-game name (offline) or account email (microsoft).
  • MCP_DISABLE_GROUPS Comma-separated tool-group keys to disable.
  • MCP_READ_ONLY Observe-only mode (no world-mutating tools).
  • MCP_ALLOWED_HOSTS Comma-separated allow-list of hosts the bot may join.

Descriptions are as written by the maker.

Menu names checked against Cursor’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Works with VS Code, with some setup first

You need a Awesome Mineflayer MCP key (create it on the maker’s site) · Install Node.js on your computer first (one time)

Let AI install it

Copy this message into a VS Code chat. The AI checks your computer, tells you which file it will change, and waits for your OK every time.

Please install the MCP server Awesome Mineflayer MCP for VS Code on this computer, in this order: 1) Check Node.js with node -v. If it is missing, tell me to install it from https://nodejs.org/en/download; do not install it yourself. 2) Use only this config (already checked by PopNx MCP): { "servers": { "awesome-mineflayer": { "type": "stdio", "command": "npx", "args": [ "-y", "awesome-mineflayer-mcp" ], "env": { "MCP_DEFAULT_AUTH": "your-value" } } } } 3) Tell me the full path of the file you will change, or the command you will run, and wait for my OK. 4) For MCP_DEFAULT_AUTH, leave "your-value" in place and tell me to paste the real value myself into the file or the app’s field. Never ask me to type a key in chat. 5) Do what we agreed, then check that the Awesome Mineflayer MCP tools really show up.

This message has no key in it. If a key is needed, the AI will ask you to paste it yourself into the file or the app’s field.

  1. Install Node.js (if you don’t have it)

    Already installed? Check first · Open Terminal, type this command and press Enter

    node -v
    • A version number such as v26.13.1 = installed, skip this step
    • "command not found" (on Windows: "is not recognized") = not installed yet, or installed but Terminal needs to be closed and reopened
    How to open Terminal

    Mac: press ⌘ + Space, type Terminal, press Enter

    Windows: open Start, type Windows PowerShell, then Open

    Not installed: Open the official download page, pick the LTS version and the click-through installer: .pkg on Mac · .msi on Windows. Double-click and follow it to the end. No curl command needed

    Open the Node.js download page ↗

    When it’s done, close Terminal, open it again and run the same command. You should see a version number: node -v

    Install once; it works for everything that needs Node.js

  2. Sign up and create a Awesome Mineflayer MCP key

    Open the maker’s site, sign up and create an API key for the next step. Check the maker’s site for pricing and free plans.

    Open the Awesome Mineflayer MCP site ↗

  3. Click this button to open VS Code

    Open in VS Code

    VS Code asks you to confirm; click Install

  4. Fill in your key

    In the Awesome Mineflayer MCP settings, MCP_DEFAULT_AUTH is empty; add your key and save

    Paste the key only into the app’s field, never into a chat or to anyone

  5. Open the AI chat in VS Code in Agent mode

  6. Try it

    Use Awesome Mineflayer MCP and tell me what you can do for me, then show me one thing

    ✓ If VS Code says it is using Awesome Mineflayer MCP or shows a Awesome Mineflayer MCP tool in the answer, you are connected

5 optional setting(s) (works without them)

The command above works without these. Add them only if you want to change something, following the maker’s description.

  • MCP_DEFAULT_HOST Server to auto-connect on startup (optional).
  • MCP_DEFAULT_USERNAME In-game name (offline) or account email (microsoft).
  • MCP_DISABLE_GROUPS Comma-separated tool-group keys to disable.
  • MCP_READ_ONLY Observe-only mode (no world-mutating tools).
  • MCP_ALLOWED_HOSTS Comma-separated allow-list of hosts the bot may join.

Descriptions are as written by the maker.

Menu names checked against VS Code’s help page on Nov 11, 2026 · your screen may differ slightly by app version

Other apps that use MCP, such as Windsurf, Zed or Gemini CLI, each add servers differently. See how in the app list.

See every app that uses MCP →

JSON settings are under “For developers” below

Stuck? Ask people who use Awesome Mineflayer MCP💬 Discussion →
For developers: Terminal commands and JSON settings

Installed on your computer

Claude Code

claude mcp add --scope user awesome-mineflayer --env MCP_DEFAULT_AUTH=your-value -- npx -y awesome-mineflayer-mcp

Claude Desktop (claude_desktop_config.json)

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

Cursor (~/.cursor/mcp.json)

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

VS Code (mcp.json)

{
  "servers": {
    "awesome-mineflayer": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "awesome-mineflayer-mcp"
      ],
      "env": {
        "MCP_DEFAULT_AUTH": "your-value"
      }
    }
  }
}

Values you fill in

  • MCP_DEFAULT_HOST env
    Server to auto-connect on startup (optional).
  • MCP_DEFAULT_USERNAME env
    In-game name (offline) or account email (microsoft).
  • MCP_DEFAULT_AUTH secret required env
    Auth mode: offline or microsoft.
  • MCP_DISABLE_GROUPS env
    Comma-separated tool-group keys to disable.
  • MCP_READ_ONLY env
    Observe-only mode (no world-mutating tools).
  • MCP_ALLOWED_HOSTS env
    Comma-separated allow-list of hosts the bot may join.

Descriptions are as written by the maker.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

At a glance

Downloads per weeki
159/wk
Connection
Runs on your computer
Latest versioni
1.3.2
Categoryi
Other
Published to registryi
Jun 29, 2026
Code last changedi
Jun 29, 2026
Maker
G0Osey99
Packages
npm: awesome-mineflayer-mcp
Website
github.com
Registry status
Active

Which apps can use it

Based on how this server connects and on each app’s own docs, checked Nov 10, 2026.

Run on your computer in

ClaudeGooseLM StudioMsty StudioCherry StudioCursorVS Code + GitHub CopilotVisual StudioWindsurf (Devin Desktop)ZedKiroClineContinueJetBrains AI AssistantClaude CodeCodex CLIGemini CLIOpenCodenodecodeWarpLibreChatRaycast

All apps, with pros and cons →

Related guides

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 19, 2026

  • ✓ Pass

    Maker matches the repo

    The registry name was verified with the GitHub account G0Osey99, which owns the repo

  • ✓ Pass

    Still maintained

    Code last changed 5 months ago

  • ✓ Pass

    Has a licence

    Uses MIT

  • – Not applicable

    Endpoint responds

    This one runs on your computer; there is no internet endpoint

  • – Not applicable

    Sign-in with OAuth

    Runs on your computer and uses local settings instead

  • … Not checked yet

    No hidden instructions in tool descriptions

    Runs on your computer; we can only read tool lists from internet endpoints

Published vulnerabilities (OSV.dev)

No entries on OSV.dev for awesome-mineflayer-mcp@1.3.2

Checks only this package version, not every dependency · checked Nov 15, 2026

What we check → · JSON

Makers: ask for a re-check or report wrong info
For makers: add a badge to your README

If you made this, paste this code into your README. The badge links back to this page.

[![Featured on PopNx MCP](https://mcp.popnx.com/badge/g0osey99-awesome-mineflayer-mcp.svg)](https://mcp.popnx.com/en/servers/g0osey99-awesome-mineflayer-mcp)

Discussion

Ask, share a tip or report that it does not work. Sorted by what people marked helpful.

No posts yet. Be the first to ask or share.

Posts here are written by users, not the PopNx team.

Sign in to post

User reviews

No reviews yet

Sign in to write a review

Compared with others in Otheri

  • More stars than 96% of the other 20749 servers in this category
  • Published to the registry more recently than 10% of the other 20749 servers in this category
  • Basic checks equal to or better than 99% of the other 20749 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Awesome Mineflayer MCP safe?

It passed 3 of 3 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

You need to fill in: MCP_DEFAULT_AUTH

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed 5 months ago, and the latest version (1.3.2) reached the registry 5 months ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Node.js on your computer.

What can I use instead?

In the same category: World Monitor, openstatus, Oh My Posh Validator, Strata, Jitsu

Similar alternatives

Same category, other makers, commands already checked. Official ones first, then by stars.

Reading a card:↓ Downloads per weeki★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

World Monitor

Real-time global intelligence on conflict, markets, energy, trade, shipping and cyber. 100 tools.

by koala73Widely used★ 90.9KUpdated 3 days ago

Runs in the cloud✓ service owner · worldmonitor.app

openstatus

Manage monitors, status pages, incidents and maintenances in your openstatus workspace.

by openstatusHQWidely used★ 9.3KUpdated 2 months ago

Runs in the cloud✓ service owner · openstatus.dev

Oh My Posh Validator

Validate oh-my-posh configurations and segment snippets against the official schema.

by JanDeDobbeleerWidely used★ 23.8K Stars for the whole repoUpdated 30 days ago

Runs in the cloud✓ service owner · ohmyposh.dev

Strata

MCP server for progressive tool usage at any scale (see https://klavis.ai)

by Klavis-AIGrowing★ 5.8KUpdated 14 months ago

Runs in the cloudRepo archived✓ klavis.ai

Jitsu

Manage Jitsu data pipelines: destinations, streams, connections, functions, live events.

by jitsucomWidely used★ 5.1KUpdated 4 months ago

Runs in the cloud✓ service owner · jitsu.com
Compared with similar ones
This one
Awesome Mineflayer MCP
World MonitoropenstatusOh My Posh ValidatorStrataJitsu
Runs whereInstalls on your computerRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to installRuns in the cloud, nothing to install
Needs a keyYesNoNoNoNoNo
Add with + in ClaudeNoNoNoNoNoNo
Basic checks3/34/44/44/41/44/4
LicenseMITAGPL-3.0AGPL-3.0MITApache-2.0MIT
PriceNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registryNo cost listed in the registry

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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
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.js20, 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):

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)

VariableDefaultPurpose
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_LIMIT25000Max characters returned by any single tool call (truncated with a marker).
MCP_EVENT_BUFFER1000Size of the in-memory event ring buffer.
MCP_THROTTLE_MS250Minimum spacing between pushed resource-update / log notifications.
MCP_PROXIMITY_RADIUS32Radius (blocks) for proximity-filtered events (entity spawns, sounds).
MCP_ACTION_TIMEOUT_MS60000Default 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_AUTHofflineDefault auth mode: offline or microsoft.
MCP_DEFAULT_VERSIONautoForce a protocol version for the default account.
MCP_DEFAULT_AUTO_RECONNECTtrueAuto-reconnect the default account on disconnect.
MCP_AUTO_CONNECTtrue†Auto-connect the default on startup († when a default is configured).
MCP_PROFILES_FOLDER /profilesMicrosoft auth token-cache directory.
AWESOME_MINEFLAYER_MCP_HOME~/.awesome-mineflayer-mcpConfig + token-cache directory.
MCP_READ_ONLYfalseObserve-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_MS0Minimum spacing between outbound chat/whisper/command sends (anti-spam).
MCP_ENABLE_RAWfalseEnable the advanced/unsafe raw protocol tool group (direct packet send/subscribe).
MCP_SCREENSHOT_WIDTH / _HEIGHT800 / 450Default get_screenshot image size (px).
MCP_SCREENSHOT_LOAD_MS2500How long to let the world render before capturing a screenshot.
MCP_VIEW_DISTANCE4Chunk 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 — 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.

  • 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, `wri

Only the beginning is shown; read the rest in the repo