Mineness

Claude, Codex, Grok, and Cursor as Minecraft teammates. Each coding-agent CLI controls its own Mineflayer player through a local MCP connection. They wait for your requests, announce what they will do, perform survival actions, and report what happened.

Run locally

The included demo server provides the example configuration, teammate datapack, and /model plugin. Run everything from this mineness folder.

Requires Java 21 or newer, Node.js 22.12 or newer, and Minecraft Java Edition 1.21.11. Install the coding-agent CLIs you want to use and sign in with their normal subscription login. No model API key is required by Mineness.

git clone --recurse-submodules https://github.com/SpectrumTantrum/mineness.git
cd mineness
npm ci
npm run setup

Setup downloads pinned Paper and SkinsRestorer jars and verifies their SHA-256 checksums. Read the Minecraft EULA, then set eula=true in mc-server/eula.txt if you accept it.

Start the server in one terminal:

npm run server

In another terminal, apply the skins once, then start your teammates:

npm run skins
npm run play -- claude codex grok cursor

You can select one provider, for example npm run play -- codex. npm run play defaults to all four. Missing or expired CLI logins must be resolved with claude auth login, codex login, grok login, or cursor-agent login.

Cursor_Bot defaults to Cursor Grok 4.6 with high reasoning, cursor-grok-4.6-high.

Grok requires one initial workspace trust decision. Prepare its configuration, open the isolated game workspace, accept its trust prompt, then quit Grok and start the launcher:

npm run play -- grok --prepare
grok --cwd "$PWD/.runtime/grok"
npm run play -- grok

Join localhost:25565 in Minecraft Java 1.21.11. The server uses offline authentication so the bots can join; it binds to localhost. Leave it local unless you intentionally configure access controls for a shared server.

Related MCP server: MCP Minecraft Remote

Play together

Type requests in Minecraft chat:

@claude chop 4 oak logs and bring them to me
@codex follow me
@grok craft a crafting table and place it next to you
@cursor build a small wall with the blocks you have
@all what are you carrying?
stop

Full nametags such as @Claude_Bot also work. @all is for conversation and status; address a named teammate for physical work. A plain stop immediately stops every body. @codex stop stops just Codex. They wait for another request afterward.

Use the server's /model command to inspect or change one teammate:

/model @cursor
/model @cursor grok-4.6 high
/model @claude sonnet high
/model @codex gpt-5.6-sol high
/model @grok grok-4.6 high
/model @cursor default

The format is /model @bot [model-id] [effort]. Model IDs must be supported by that bot's CLI and account. Without a model, it shows the configured model and connection status. default restores the project default. The command reconnects only the selected teammate, stops its current action, and preserves its Minecraft location and inventory. If the new model fails to connect, the launcher attempts to restore the previous one and reports the result in chat.

Selections persist in .runtime/<provider>/model.json. Human players can use the command through the mineness.model permission, enabled by default on this local server.

Keep requests within survival abilities. A bot needs materials to build, ingredients to craft, and a suitable tool for blocks that require one. It can navigate, chop nearby trees, gather blocks, craft, place up to 32 blocks per call, deliver items, and follow a visible player. Each physical action has a 45-second limit, and the model can chain actions for a larger request. Dense terrain or inaccessible targets can still require a different approach.

The models see structured tool results. look_around includes leaves and leaf litter, and its inspect argument reports exact blocks at requested coordinates, including air. Before building, inspect the footprint and the blocks underneath it. place_blocks clears grass and leaf litter at the requested positions, preserves solid blocks, and skips blocks already placed correctly. High walls and roofs can require temporary access steps made from the bot's materials.

Skin setup uses a temporary connection for each body. Apply skins before starting the agents. SkinsRestorer's live refresh respawns a player and can disrupt Mineflayer inventory and movement state. On subsequent launches, the server supplies the saved skin without refreshing it.

How it works

Minecraft chat → named teammate's inbox → its coding-agent CLI
                       ↑                         ↓
                 Minecraft body ← Mineness MCP tools

Each CLI starts one src/server.js --username NAME_Bot process. A lock prevents a second local session from taking the same body. The ten MCP tools are wait_for_mention, say, look_around, goto, chop_tree, gather_blocks, craft_item, place_blocks, give_items_to_player, and follow_player.

The shared operating prompt is in prompts/shared-operating-prompt.md. The launcher builds provider-specific configurations in ignored .runtime/ directories and disables unrelated tool access. Minecraft chat cannot run slash commands through say. Bot messages do not wake other bots. The raw stop listener runs in the body process, so stopping does not wait for a model response.

CLI output goes to .runtime/claude.log, .runtime/codex.log, .runtime/grok.log, and .runtime/cursor.log. Completed tool calls are recorded in calls.jsonl, including duration, result, and failures. These logs, account settings, server passwords, player data, and worlds are excluded from Git.

Press Ctrl+C in the launcher terminal to disconnect its teammates. Their Minecraft inventories remain in the world. Type stop in the server terminal to save and stop Paper. python3 scripts/rcon.py list is available for local administration and reads the generated RCON password from the local server configuration.

Checks

npm test
npm run test:game
node scripts/test-building.mjs
node scripts/test-agents.mjs claude codex grok cursor
node scripts/test-model-command.mjs

npm test checks routing, inbox behavior, cancellation, deadlines, duplicate-body protection, and model switching with rollback. test:game requires the local server; it creates a temporary test platform only after verifying that the space is empty, exercises real mining, crafting, placement, navigation, recipient pickup, following, and stopping, then removes the platform.

test-agents.mjs requires the selected CLI teammates to be running. It sends requests through a clearly named test player and verifies actual delivery to that player's inventory. It temporarily moves the selected bots to an empty test platform and restores their positions afterward. Run these integration checks when other players are not using that area.

test-building.mjs uses a separate test bot and an empty temporary platform. It checks bulk crafting against server inventory, terrain inspection, building over leaf litter, a complete small shelter with a roof, and harvesting a tree beside an isolated canopy log. It removes the platform afterward.

The /model plugin's Java source and compiled jar are in mc-server/model-command/. Setup installs the jar. To rebuild it, use a JDK 21 or newer and run npm run build:plugin after Paper has started once and extracted its libraries. Restart Paper after rebuilding. The launcher and server share the local .runtime directory.

test-model-command.mjs sends real player slash commands, temporarily switches Cursor's reasoning effort, verifies that the other bots stay connected, and restores Cursor's original model. Run it when Cursor is idle.

Sources and attribution

The starting Mineflayer/MCP connection code came from yuniko-software/minecraft-mcp-server, under Apache-2.0. The running implementation uses the dependencies pinned in package-lock.json; the old reference checkout is not required. See LICENSE and NOTICE.

The small client collision margin follows the proposed Minecraft 1.21.x pathfinder fix. It prevents the bot from aligning exactly with block edges, where server collision checks can reject its movement.

CLI configuration follows the official Claude Code CLI reference, Codex configuration reference, Grok headless documentation, and Cursor CLI permissions. Skins use SkinsRestorer and the separate Mineness skins repository.

Mineness is an independent project. Product names and logos identify the represented teammates; they do not imply endorsement.