Awesome Mineflayer MCP — Minecraft bot MCP server
Hands an AI agent control of a Mineflayer bot: walking, mining, crafting, fighting, building. Works in Claude, Cursor, Codex and other MCP clients.
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-mcpWhat Awesome Mineflayer MCP 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.
What it helps with
- 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 for the agent
- Connect to
localhostasDevBotusingauth: "offline", then runget_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
How to install Awesome Mineflayer MCP
Platform CLI
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-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Platform CLI
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-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values. 1 more environment variable is in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Awesome Mineflayer MCP
How do I install Awesome Mineflayer MCP in Claude Code?
Run claude mcp add awesome-mineflayer-mcp -- npx -y awesome-mineflayer-mcp. To pass environment variables, use the form with --env for MCP_DEFAULT_HOST, MCP_DEFAULT_USERNAME, MCP_DEFAULT_AUTH and others, plus --transport stdio.
What does Awesome Mineflayer MCP do?
It is an MCP server built on Mineflayer. The agent gets tools to drive a Minecraft bot: move, mine, craft, fight, use containers, chat.
What do I need before running it?
Node.js 20 or newer and a Minecraft Java Edition server. Microsoft auth is required on online-mode servers; offline mode works with just a username.
