Minecraft MCP Player

Control your own Minecraft Java character with Codex or another MCP client, in a normal single-player world. No second bot player, browser game, dedicated server, or Open to LAN is needed in native player mode.

This is a derivative of yuniko-software/minecraft-mcp-server, based on commit 240c8cec337ce152cc9e058ebdef511055808406. It preserves the original 22 MCP tools and adds a Fabric client execution backend, get-state, and stop-actions (24 tools total). The original Mineflayer bot backend is still available.

Status: experimental, working prototype. The project owner tested Codex controlling the player in survival mode, including autonomous item collection, and reported that it plays relatively smoothly. A separate developer smoke test verified an actual native-player jump (about 1.25 blocks), a block query, and stopping. A simulated Fabric peer verified dispatch of all 22 original tools and cancellation over real MCP stdio. This does not establish that every recipe, terrain, creative-mode action, or complex building task works.

中文说明 · Original upstream README

How it works

Codex / MCP client -> MCP stdio server -> authenticated localhost bridge
                                         -> Fabric mod -> your Minecraft player

The model receives the tool descriptions and schemas through MCP. It plans actions, calls tools, examines actual results, and chooses the next step. The server itself does not require an Alibaba or OpenAI API key. Your MCP client provides the model. Voice UI and paid voice services are not included in this repository.

Related MCP server: minecraft-agent-body

Requirements

• Minecraft Java 1.21.11, Fabric Loader 0.18.4, Fabric API 0.141.6+1.21.11.

• Java 21; Node.js 22+ recommended (upstream supports >=20.10).

• Baritone API Fabric 1.17.0, installed as a separate mod and used as a build dependency.

• Codex or another local MCP client. Windows was used for actual gameplay testing; other operating systems are not gameplay-validated.

Survival mode is the recommended starting point. fly-to requires the player to have flight permission (normally creative mode); it does not grant flight or run cheats.

Install and build

Clone this repository and open a terminal in its root:

npm ci
npm run build
node scripts/fetch-baritone.mjs

The fetch script downloads the separate Baritone jar from its upstream release and verifies its SHA256. Build the Fabric mod with Java 21:

cd fabric-mod
# Windows:
.\gradlew.bat build
# Linux/macOS instead:
./gradlew build

Copy these jars into the mods folder of the Minecraft instance you actually launch:

• Fabric API for the version above (obtain it separately).

• fabric-mod/libs/baritone-api-fabric-1.17.0.jar.

• fabric-mod/build/libs/astra-voice-1.0.0.jar (the runtime jar, not the -sources.jar).

Back at the repository root, generate the local pairing file, using your actual game instance directory (the folder containing mods, config, and saves):

node scripts/init-player-config.mjs "C:/path/to/your/minecraft-instance"

This generates a random local token and refuses to overwrite an existing config/astra-voice.json. For an existing installation, reuse its pairing file and set backend.autoStart to false to keep an old voice backend from competing with the MCP bridge. Never publish the pairing file.

Connect Codex

Add the following to your Codex config.toml (normally %USERPROFILE%/.codex/config.toml on Windows). Replace both paths. Existing settings should be preserved.

[mcp_servers.minecraft]
command = "node"
args = ["C:/path/to/minecraft-mcp-player/dist/main.js", "--control", "player", "--player-config", "C:/path/to/your/minecraft-instance/config/astra-voice.json"]
startup_timeout_sec = 30
tool_timeout_sec = 300

Use the absolute path to node.exe if your desktop app cannot find Node on PATH. No MINECRAFT_PLAYER_PROJECT variable or separate voice-project installation is needed for a fresh installation of this repository.

Fully restart Codex, use a local session on the computer running Minecraft, launch the Fabric profile, enter a single-player world, and close all game menus. Close any other voice/MCP backend using port 8765 first; only one backend can own that bridge at a time. If the connection has not appeared, run /astra connect in Minecraft.

Try this first:

Use the minecraft MCP to inspect my player state and inventory. Then jump once and report the observed result.

Then try a survival goal:

Collect enough wood to craft a crafting table and a wooden pickaxe. Check the results after each step and tell me if you get stuck.

The MCP welcome enables control once per world session. F9 in Minecraft stops and disarms control. F8 enables it again after you close menus and release movement keys. Reconnecting after a stop may require F8. stop-actions cancels current work but does not provide the same persistent disarm as F9.

Switching focus can pause single-player Minecraft. Turn off Pause on lost focus (F3+P in Java Edition) if needed and leave the game out of menus. If actions are rejected, inspect get-state and /astra status before retrying.

Tools

Tools operate through normal client mechanics and the installed Baritone API. Queries cover loaded nearby terrain, not the whole world. Navigation can fail on difficult terrain. Crafting supports the translated vanilla recipes; arbitrary modded recipes are not guaranteed. Smelting uses an available furnace/blast furnace/smoker and conservatively rejects occupied slots. Container GUI mirroring, complete chest management, automatic combat, and reliable autonomous large builds are not implemented merely by exposing these tools.

Original bot mode remains the default for compatibility. Always pass --control player --player-config ... for your own character. Without those flags the upstream Mineflayer backend is used; see the upstream README for bot/server instructions.

Development and checks

npm run build
npm test
npm run test:native

test:native uses a simulated Fabric peer and real MCP SDK stdio transport, and makes no cloud/model calls. It is a transport and mapping check, not a gameplay benchmark. The Fabric sources also include Java unit tests run by Gradle's build task.

Dependency status

The retained upstream dependency tree currently has unresolved npm audit advisories. This prototype is intended for a local trusted MCP client and loopback bridge; it has not undergone a security audit. Dependency upgrades are separate work and are not silently applied as part of this fork.

Attribution and licensing

• Original MCP server: yuniko-software/minecraft-mcp-server, Apache-2.0. Original Git history and the root LICENSE are preserved. The native TypeScript adapter and repository helper scripts are distributed under Apache-2.0.

• Fabric controller: adapted from tommywalteryespls-bit/minecraft-ai-player (base commit d77377957fbfbb55de179165165421c160b0aa9c) and extended locally for native MCP. Its MIT license is preserved in fabric-mod/LICENSE.

• Mindcraft references and separately installed Baritone (LGPL-3.0): see THIRD_PARTY_NOTICES.md. Baritone remains a separate, replaceable dependency; its binary is not committed here.

Minecraft, Fabric API, Node.js, Java runtimes, accounts, model keys, game saves, and local pairing tokens are not bundled. This project is not affiliated with Mojang or Microsoft.