# Awesome Mineflayer MCP

Hands an AI agent control of a Mineflayer bot: walking, mining, crafting, fighting, building. Works in Claude, Cursor, Codex and other MCP clients.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 6
- Author: G0Osey99
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/G0Osey99/awesome-mineflayer-mcp
- Updated: 2026-06-29
- HTML: https://affpapa.org/en/nevibecode/mcp/awesome-mineflayer-mcp

## What it does

The server connects to a Java Edition Minecraft world through Mineflayer and exposes 123 typed tools in 26 groups. That covers movement, gathering, inventory, combat, containers, chat, waypoints, and macros for building or digging. Vision tools return first-person screenshots and schematic maps, so the agent can check what it actually did. Every tool result has plain text for humans plus `structuredContent` for the model.

Pathfinding and behaviour come from the Mineflayer packages: `mineflayer-pathfinder`, `mineflayer-pvp`, `mineflayer-collectblock`, `mineflayer-auto-eat`, `mineflayer-armor-manager`. You need Node.js 20 or newer and a Minecraft server. On an online-mode server, add a Microsoft account with `auth: "microsoft"`.

The game version is detected automatically, yet some tools such as `elytra_fly` only exist on newer releases. If client and server disagree, the bot gets kicked with an outdated client or server message, and passing an explicit version fixes it. `MCP_READ_ONLY` restricts the agent to observe-only tools, while `MCP_COMMAND_DENY` and `MCP_COMMAND_ALLOW` filter slash commands. Leave `MCP_ALLOWED_HOSTS` unset and the bot may connect to any address.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MCP_DEFAULT_HOST`, `MCP_DEFAULT_USERNAME`, `MCP_DEFAULT_AUTH`, `MCP_DISABLE_GROUPS`, `MCP_READ_ONLY`, `MCP_ALLOWED_HOSTS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MCP_DEFAULT_HOST=<MCP_DEFAULT_HOST> --env MCP_DEFAULT_USERNAME=<MCP_DEFAULT_USERNAME> --env MCP_DEFAULT_AUTH=<MCP_DEFAULT_AUTH> --env MCP_DISABLE_GROUPS=<MCP_DISABLE_GROUPS> --env MCP_READ_ONLY=<MCP_READ_ONLY> --transport stdio awesome-mineflayer-mcp -- npx -y awesome-mineflayer-mcp
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Codex

**Platform CLI**
```bash
codex mcp add awesome-mineflayer-mcp --env MCP_DEFAULT_HOST=<MCP_DEFAULT_HOST> --env MCP_DEFAULT_USERNAME=<MCP_DEFAULT_USERNAME> --env MCP_DEFAULT_AUTH=<MCP_DEFAULT_AUTH> --env MCP_DISABLE_GROUPS=<MCP_DISABLE_GROUPS> --env MCP_READ_ONLY=<MCP_READ_ONLY> -- npx -y awesome-mineflayer-mcp
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "awesome-mineflayer-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "awesome-mineflayer-mcp"
            ],
            "env": {
                "MCP_DEFAULT_HOST": "<MCP_DEFAULT_HOST>",
                "MCP_DEFAULT_USERNAME": "<MCP_DEFAULT_USERNAME>",
                "MCP_DEFAULT_AUTH": "<MCP_DEFAULT_AUTH>",
                "MCP_DISABLE_GROUPS": "<MCP_DISABLE_GROUPS>",
                "MCP_READ_ONLY": "<MCP_READ_ONLY>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "awesome-mineflayer-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "awesome-mineflayer-mcp"
            ],
            "env": {
                "MCP_DEFAULT_HOST": "<MCP_DEFAULT_HOST>",
                "MCP_DEFAULT_USERNAME": "<MCP_DEFAULT_USERNAME>",
                "MCP_DEFAULT_AUTH": "<MCP_DEFAULT_AUTH>",
                "MCP_DISABLE_GROUPS": "<MCP_DISABLE_GROUPS>",
                "MCP_READ_ONLY": "<MCP_READ_ONLY>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MCP_DEFAULT_HOST=<MCP_DEFAULT_HOST> -e MCP_DEFAULT_USERNAME=<MCP_DEFAULT_USERNAME> -e MCP_DEFAULT_AUTH=<MCP_DEFAULT_AUTH> -e MCP_DISABLE_GROUPS=<MCP_DISABLE_GROUPS> -e MCP_READ_ONLY=<MCP_READ_ONLY> awesome-mineflayer-mcp npx -y awesome-mineflayer-mcp
```
Replace <…> with your own values. 1 more environment variable is in the server README

## When to use it
- put a bot into a Minecraft world and walk it to coordinates
- gather blocks and sort the loot into chests
- craft items from what the bot is carrying
- see what the bot sees via a screenshot and map
- repeat a build or dig pattern from a macro

## Example prompts
- Connect to `localhost` as `DevBot` using `auth: "offline"`, then run `get_connection_status`
- Mine ten oak logs near the bot and put them in the closest chest
- Take a first-person screenshot and tell me what is around the bot

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md