This server acts as an MCP bridge that allows AI agents to control a Minecraft player and the server itself on a PaperMC server. It provides a wide range of tools categorized as follows:
Movement & View: look_at to face a position, move_to to walk/sprint to coordinates (with timeout and speed options), jump, sprint/sneak toggles, and stop to cancel movement.
Block Interaction: break_block and place_block at coordinates (with optional face and world, works without a player).
Entity & Combat: attack and interact_entity using entity IDs from get_nearby_entities; use_item for right-click actions.
Inventory Management: get_inventory, equip_item (to main/offhand/armor slots), drop_item, swap_hands, and give_item to add items directly.
World & Player Queries: get_player_state (health, position, gamemode, etc.), get_block_at, get_nearby_entities, and get_time_weather.
Chat: send_chat sends messages as the player.
Teleport & Gamemode: teleport with optional world, yaw, pitch; set_gamemode to survival/creative/adventure/spectator.
World & Server Control: set_time (tick values: 0=sunrise, 6000=noon, 13000=sunset, 18000=midnight), set_weather (clear, rain, thunder), summon_entity (spawn mobs/entities), and run_command to execute console commands.
Player-less Operation: Many world-level tools work without any player online, enabling automated building.
Extensible: All tools accept an optional player argument to target a specific online player, defaulting to the first online player.
Showcase Scripts: Includes pre-built scripts (e.g., build-castle, build-lighthouse) demonstrating large-scale automated building.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@minecraft-mcp break the block I'm looking at and place a torch"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local MCP server that lets AI harnesses (Claude Code, Codex, Hermes, ...) perform every action a Minecraft player can — move, jump, break/place blocks, fight, manage inventory, chat — plus op-level extras (teleport, gamemode, weather/time, summon entities, console commands).
AI Harness (Claude Code / Codex / Hermes)
│ stdio (MCP protocol)
▼
src/ Node + TypeScript MCP server (this repo, `npm run dev` / dist/index.js)
│ WebSocket, JSON frames (see docs/bridge-protocol.md)
▼ ws://127.0.0.1:8765
plugin/ Java Paper plugin `minecraft-mcp-bridge`
│ Bukkit/Paper API
▼
Local PaperMC server (server/ dir) — you join as the controlled playerThe harness controls whoever is online on the server (you). Every tool
accepts an optional player argument to target a specific online player.
Related MCP server: MCP Minecraft Remote
Node.js ≥ 18
JDK ≥ 21 to build the plugin (JDK 24 works; the plugin is compiled for Java 21 bytecode)
A Minecraft Java Edition client matching the server version
npm install # install MCP server deps
node scripts/setup-server.mjs 26.2 # download Paper 26.2 into server/, accept EULA
npm run start:server # build plugin, install it, launch the serverNotes:
setup-server.mjs takes an optional version argument (26.2, 1.21.11,
...). Without one it downloads the latest 1.21.x.
Paper 26.1+ requires Java 25 to run (not just build). If a portable JDK is
extracted under .jdk/ (e.g. .jdk/jdk-25.0.4+7/), start-server.mjs uses
it automatically instead of the system java.
Join localhost with a client matching the server version. The server runs
with online-mode=false for local dev.
To verify everything end-to-end (requires the server running and a player online):
npm run smoke:bridge # exercises every tool against the live serverThe MCP server runs over stdio. Build first (npm run build), then register:
Claude Code (claude mcp add):
claude mcp add minecraft -- node /path/to/minecraft-mcp/dist/index.jsCodex / other harnesses — equivalent stdio entry:
{
"mcpServers": {
"minecraft": {
"command": "node",
"args": ["/path/to/minecraft-mcp/dist/index.js"]
}
}
}Environment variable MINECRAFT_MCP_BRIDGE_URL overrides the bridge address
(default ws://127.0.0.1:8765).
All tools take an optional player (defaults to the first online player).
Category | Tool | What it does |
Movement |
| Face a block/position |
| Walk/sprint toward coordinates (timeout-aware) | |
| Movement state control | |
Interaction |
| Block manipulation |
| Right-click / combat | |
Inventory |
| Full inventory control |
Info |
| World & player queries |
Chat |
| Chat as the player |
Extras |
| Beyond player capabilities |
The full tool/command contract is documented in docs/bridge-protocol.md.
npm run typecheck # TS typecheck
npm run build # compile MCP server to dist/
npm test # bridge unit tests (mock socket, no Minecraft needed)
npm run build:plugin # build the Paper plugin jar (Gradle shadowJar)Plugin jar output: plugin/build/libs/minecraft-mcp-bridge-0.1.0.jar.
Bridge port is configurable in plugin/src/main/resources/config.yml
(runtime copy: server/plugins/minecraft-mcp-bridge/config.yml).
move_to is velocity-based steering, not pathfinding; it hops over 1-block
obstacles but won't route around walls.
Survival break_block uses a fixed 1s delay regardless of tool/hardness.
use_item / interact_entity fire the Bukkit events but don't reproduce
vanilla effects (eating, trading, mounting).
Controls an online player; fake-player NPCs are future work.
World-level commands (place_block, break_block, get_block_at,
get_heightmap, run_command, set_time, set_weather, summon_entity with
explicit coordinates) work with no player online, against the default
world — so agents can build 24/7. Use run_command with forceload add to
keep build regions' chunks loaded.
The scripts/ directory contains the builds that grew the world, all driven
through the bridge and verified with get_block_at sampling:
build-house.ts — the original medieval house smoke test
build-castle.ts / build-lighthouse.ts / build-bridge.ts — the three
terrain-fitted marvels (SE hill keep, W shore lighthouse, channel arch bridge)
build-aqueduct.ts / build-forum.ts / build-colossus.ts /
build-span.ts / build-skyfall.ts / build-roads.ts — the Aurelian
Reach megastructure program (run in that order)
survey-terrain.ts / fine-survey.ts — ASCII relief maps from
get_heightmap, used to pick sites from real terrain data
lib-build.ts — shared Builder: plan queue with last-wins dedupe,
carve-after-place, chunked console fills (vanilla 32768 limit), forceload
helpers, tolerant placement, verification
MIT
Face and attack an entity once. Use an entity id from get_nearby_entities.
Inputs: entity_id (required), player.
Face and break the block at the given coordinates. Instant in creative mode; takes time in survival and may time out.
Inputs: x (required), y (required), z (required), player.
Drop items from the player's inventory onto the ground. Defaults to one of the currently held item.
Inputs: item, count, player.
Move the first matching stack from the player's inventory into a slot (main hand by default). Fails if the player doesn't have the item.
Inputs: item (required), slot, player.
Read which material occupies the block at the given coordinates.
Inputs: x (required), y (required), z (required), world, +1 more.
Read the player's inventory: hotbar, main storage, armor, offhand contents and the currently held hotbar slot.
Inputs: player.
List entities near the player (mobs, players, items, ...) with their ids, types, positions and distances. Entity ids are used with attack and interact_entity.
Inputs: player, radius.
Read the player's position, world, view direction, health, food, XP, gamemode, movement flags, and held item.
Inputs: player.
Read the time of day and weather for a world (default: the player's world).
Inputs: world, player.
Add items directly to the player's inventory (no crafting or pickup needed).
Inputs: item (required), count, player.
Right-click an entity (e.g. open a villager trade or mount). Use an entity id from get_nearby_entities.
Inputs: entity_id (required), player.
Make the player jump once.
Inputs: player.
Instantly rotate the player's view to face the given block or entity position.
Inputs: x (required), y (required), z (required), player.
Walk the player toward the given coordinates (looking at the target and holding forward, jumping over 1-block obstacles). Resolves once within 1.5 blocks horizontally; call stop to cancel a long walk.
Inputs: x (required), y (required), z (required), speed, +2 more.
Place a block of the given material at the coordinates, against the adjacent face. Uses the player's inventory (or places directly in creative mode).
Inputs: x (required), y (required), z (required), block (required), +2 more.
Execute a vanilla or plugin command from the server console, without the leading slash (e.g. "say hello"). Returns the command output, possibly empty.
Inputs: command (required), player.
Send a chat message as the player; it appears in game chat and triggers normal chat events.
Inputs: message (required), player.
Change the player's gamemode (creative enables instant breaking and free placement).
Inputs: mode (required), player.
Set the time of day for a world in ticks (0 = sunrise, 6000 = noon, 13000 = sunset, 18000 = midnight).
Inputs: time_ticks (required), world, player.
Set the weather for a world (default: the player's world).
Inputs: weather (required), world, player.
Enable or disable sneaking (crouching) for the player.
Inputs: enabled (required), player.
Enable or disable sprinting for the player.
Inputs: enabled (required), player.
Cancel any in-progress move_to, stop the player's movement, and clear sprint/sneak.
Inputs: player.
Spawn an entity (e.g. zombie, cow, armor_stand) at the given coordinates, or 2 blocks in front of the player by default.
Inputs: type (required), x, y, z, +1 more.
Swap the items in the player's main hand and off hand.
Inputs: player.
Instantly teleport the player to coordinates, optionally in another world and with a given view direction.
Inputs: x (required), y (required), z (required), yaw, +3 more.
Right-click with the item in the player's main hand.
Inputs: player.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 27 tools
Each tool targets a distinct action or query in Minecraft, from movement (sprint, sneak, jump, move_to, teleport) to interaction (break_block, place_block, attack, interact_entity) and data retrieval (get_inventory, get_player_state, get_block_at). Even similar operations like use_item and interact_entity are clearly differentiated by targeting items vs. entities.
Tool names follow a consistent verb_noun snake_case pattern: get_* for state queries, set_* for world modifications, and bare action verbs for player actions. There are no mixed conventions or vague generic names like 'process' or 'do_thing'.
27 tools is slightly above the typical well-scoped range, but the breadth is justified by Minecraft's complex mechanics (movement, inventory, world editing, entities, time/weather, commands). The set feels comprehensive rather than bloated, with each tool serving a concrete purpose.
The surface covers most core Minecraft interactions: movement, block manipulation, inventory management, entity interaction, world queries, and environment settings. Minor gaps exist (e.g., no explicit crafting action, no block entity inspection like chests), but agents can work around these via run_command or give_item.
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server for AI dialogue using various LLM models via AceDataCloud
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
