mcpylib-mcp
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., "@mcpylib-mcp Build a small oak cabin with a porch next to Steve."
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.
MCPyLib-mcp
An MCP server that lets AI agents such as Claude Code, Claude Desktop, Cursor and VS Code control a Minecraft server through MCPyLib. Agents can build structures, survey terrain, and manage players, entities, the world, chat and scoreboards.
MCP client ──(MCP: stdio or HTTP)──> mcpylib-mcp ──(MCPyLib protocol: TCP 65535 + token)──> MCPyLib plugin
(Claude, Cursor, VS Code...) (this project) on Paper/SpigotOnce it is connected, you can ask things like:
"Who is online, and where is Steve?"
"Build a small oak cabin with a porch next to Steve."
"Survey 30 blocks around spawn and tell me where the flattest spot is."
"Make it night, start a thunderstorm and give everyone night vision."
Features
86 tools covering the whole MCPyLib client API. They are organised in seven groups. Every tool has typed, validated parameters and returns structured JSON. MCP annotations mark each tool as read-only, destructive or idempotent, so clients can auto-approve reads and ask before destructive changes.
Block tools designed for language models.
get_blocksreturns a region as text layers (floor plans stacked bottom to top).build_from_layersaccepts the same format, so an agent can read, edit and write back a build.get_height_mapfinds the ground in one call.Safety controls:
a per-call block limit;
a read-only mode;
tool allowlists and denylists (by name, glob or group);
the token is never logged.
Resources and prompts: a live server-status resource, player lookups and a building guide, plus "build a structure" and "survey an area" prompts.
stdio and streamable HTTP transports.
Related MCP server: Brainstorm
Requirements
A Paper or Spigot server running Minecraft 26.1 or newer (Java 25) with the MCPyLib plugin 1.2.0 or newer.
uv, which provides
uvx. If you don't use uv, you need Python 3.11+ and pip.
Quick start
Install the plugin. Put the MCPyLib plugin jar from the MCPyLib releases into the server's
plugins/folder and restart the server.Get a token. Run
/mcpylib tokenin the server console, or in game with themcpylib.adminpermission. Copy the token it prints.Check that the MCP server runs. This needs no token and does not connect to Minecraft:
uvx --from git+https://github.com/treeleaves30760/MCPyLib-mcp mcpylib-mcp --list-toolsAdd it to your MCP client using one of the configurations below, then ask your agent who is online.
uvx downloads and caches the server the first time it runs. Add --refresh once to pick up newer commits.
To pin a version, append @<tag-or-commit> to the URL.
If you prefer pip, run pip install git+https://github.com/treeleaves30760/MCPyLib-mcp. That installs the
mcpylib-mcp command.
Connect your MCP client
In every example, replace <token> with your token. If Minecraft runs on a different machine, also set
MCPYLIB_HOST. If you changed the plugin's port, set MCPYLIB_PORT too.
Claude Code
claude mcp add mcpylib -e MCPYLIB_TOKEN=<token> -- uvx --from git+https://github.com/treeleaves30760/MCPyLib-mcp mcpylib-mcpRemote server: add
-e MCPYLIB_HOST=192.168.1.20.All projects: add
--scope userbeforemcpylib.Check the connection: run
claude mcp listor use/mcpin a session.
Shared projects. To share the server in a project, add a .mcp.json file that reads the token from your
environment. This keeps the token out of the repository:
{
"mcpServers": {
"mcpylib": {
"command": "uvx",
"args": ["--from", "git+https://github.com/treeleaves30760/MCPyLib-mcp", "mcpylib-mcp"],
"env": { "MCPYLIB_TOKEN": "${MCPYLIB_TOKEN}" }
}
}
}Claude Desktop
Open the config file with Settings > Developer > Edit Config. The file is
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS and%APPDATA%\Claude\claude_desktop_config.jsonon Windows.Add the server:
{ "mcpServers": { "mcpylib": { "command": "uvx", "args": ["--from", "git+https://github.com/treeleaves30760/MCPyLib-mcp", "mcpylib-mcp"], "env": { "MCPYLIB_TOKEN": "<token>", "MCPYLIB_HOST": "localhost", "MCPYLIB_PORT": "65535" } } } }Restart Claude Desktop.
If Claude Desktop cannot find uvx, for example with a spawn uvx ENOENT error, put the full path in
command. Get it from which uvx on macOS or Linux, or where uvx on Windows.
Cursor
Add the server to ~/.cursor/mcp.json to use it in every project, or to .cursor/mcp.json for one project:
{
"mcpServers": {
"mcpylib": {
"command": "uvx",
"args": ["--from", "git+https://github.com/treeleaves30760/MCPyLib-mcp", "mcpylib-mcp"],
"env": { "MCPYLIB_TOKEN": "<token>" }
}
}
}VS Code
Add the server to .vscode/mcp.json in your workspace. For every workspace, use MCP: Open User
Configuration instead. With this configuration, VS Code asks for the token the first time the server starts,
so the token is not written into the file:
{
"inputs": [
{
"type": "promptString",
"id": "mcpylib-token",
"description": "MCPyLib token (run /mcpylib token on the Minecraft server)",
"password": true
}
],
"servers": {
"mcpylib": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/treeleaves30760/MCPyLib-mcp", "mcpylib-mcp"],
"env": { "MCPYLIB_TOKEN": "${input:mcpylib-token}" }
}
}
}Other clients, and streamable HTTP
Any client that launches stdio servers works the same way. Use the command
uvx --from git+https://github.com/treeleaves30760/MCPyLib-mcp mcpylib-mcp with MCPYLIB_TOKEN set in its
environment.
Some clients connect to a URL instead. Streamable HTTP also lets several clients share one server process. To use it, start the server yourself:
MCPYLIB_TOKEN=<token> uvx --from git+https://github.com/treeleaves30760/MCPyLib-mcp mcpylib-mcp --transport http --port 8000In PowerShell, run $env:MCPYLIB_TOKEN = "<token>" first. Then point each client at
http://127.0.0.1:8000/mcp:
Claude Code:
claude mcp add --transport http mcpylib http://127.0.0.1:8000/mcpVS Code:
"mcpylib": { "type": "http", "url": "http://127.0.0.1:8000/mcp" }Cursor:
"mcpylib": { "url": "http://127.0.0.1:8000/mcp" }
The HTTP endpoint has no authentication of its own; read Safety before exposing it.
Configuration
Settings come from environment variables. Command-line flags of the same name take precedence.
Variable | Flag | Default | Meaning |
|
| required | Token printed by |
|
|
| Host of the Minecraft server that runs the MCPyLib plugin. |
|
|
| Plugin port ( |
|
|
| Seconds to wait for each reply from the plugin. |
|
|
| The most blocks one tool call may read or change. |
|
|
| Register only tools that do not change the world. |
|
| all tools | Register only these tools. Entries are names, globs ( |
|
| none | Never register these tools. Same syntax; the denylist wins over the allowlist. |
|
|
|
|
|
|
| Address the HTTP transport binds to. |
|
|
| Port of the HTTP transport. The endpoint is |
|
|
|
|
--mc-hostand--mc-portpoint at Minecraft.--hostand--portconfigure the MCP HTTP transport.Lists are separated by commas or spaces. Booleans accept
true/false,1/0,yes/noandon/off.--list-toolsprints the tools your settings enable and exits. It needs no token, so it is a quick way to check a filter.--versionand--helpwork the same way.
Examples:
# Let an agent look around but change nothing
mcpylib-mcp --read-only
# Building only: block tools plus player positions, never run_command
MCPYLIB_ALLOWED_TOOLS="group:blocks get_players get_player_position" mcpylib-mcp
# Everything except raw console commands and mass entity removal
MCPYLIB_DENIED_TOOLS=run_command,kill_entities mcpylib-mcpTools
Tool groups: server, blocks, players, world, entities, chat and scoreboard. The
Access column means:
read-only: never changes the world. These tools stay available in read-only mode.
destructive: can overwrite or delete things that cannot be restored.
changes: modifies the world without destroying anything.
Coordinates follow Minecraft: +X is east, +Z is south and +Y is up. Block, world and particle tools act on the server's main world.
server
Tool | What it does | Access |
| List online players (name, UUID, game mode) and the player limit. | read-only |
| Run any Minecraft command as the server console. The block limit does not apply; see Safety. | destructive |
blocks
Tool | What it does | Access |
| Return the block id at one position, e.g. | read-only |
| Read every block in a box, as text layers, an index array or block counts. | read-only |
| For each column of an area, the Y of the highest non-air block, optionally ignoring leaves or plants. | read-only |
| Place one block, with optional block state and sign text, replacing what is there. | destructive |
| Fill a box with one block; use | destructive |
| Copy a box of blocks to another place (at most 32,768 blocks, a plugin limit). | destructive |
| Place many different blocks in one call from a 3D array (MCPyLib's bulk edit). | destructive |
| Build from text layers: floor plans stacked bottom to top, each character one block. | destructive |
players
Tool | What it does | Access |
| Block position of an online player's feet. | read-only |
| Teleport a player, optionally setting where they face. | changes |
| Set a player's game mode. | changes |
| Add items to a player's inventory. | changes |
| List a player's non-empty inventory slots with items, amounts and enchantments. | read-only |
| Put an item stack into one slot, replacing what was there. | destructive |
| Remove all items, or one item type, from a player's inventory. | destructive |
| Enchant the item in a player's main hand. | changes |
| Give a player a status effect such as speed or night vision. | changes |
| Remove one or all status effects. | changes |
| A player's level, points and progress to the next level. | read-only |
| Add or set experience points or levels. | changes |
| Set where a player respawns. | changes |
| Whether a player has completed an advancement. | read-only |
| Grant or revoke an advancement. | destructive |
| Teleport players to random surface positions around a point ( | changes |
world
Tool | What it does | Access |
| Time of day: ticks, phase (day, sunset, night, sunrise) and clock time. | read-only |
| Set or advance the time, by preset ( | changes |
| Clear, rain or thunder, optionally for a duration. | changes |
| Set the difficulty. | changes |
| Current value of a game rule. | read-only |
| Set a game rule and return the value the server now reports. | changes |
| Set the world spawn point. | changes |
| Set the game mode new players get. | changes |
| The world border's size, centre, damage and warning settings. | read-only |
| Change any combination of world-border settings in one call. | changes |
| Whether the chunk containing a block is force-loaded. | read-only |
| Force-load a chunk, or stop force-loading it. | changes |
| Change the biome of a box. | destructive |
| Find the nearest structure of a type, such as a village. | read-only |
| Generate a feature (tree, ore vein...) as world generation does. | destructive |
| Generate a whole structure (village, temple...). | destructive |
| Generate a jigsaw structure from a template pool. | destructive |
| Place a saved structure template. | destructive |
| Roll a loot table and drop the items at a position. | changes |
entities
Tool | What it does | Access |
| Spawn an entity and return its UUID, which the other entity tools use. | changes |
| Remove entities by type, a player, or all non-player entities (at most 1,000 per call). | destructive |
| Delete one entity without drops. | destructive |
| An entity's type, name, position, rotation, velocity, health and AI state. | read-only |
| Move an entity to an exact position. | changes |
| Push an entity by setting its velocity vector. | changes |
| Turn an entity without moving it. | changes |
| Turn a mob's AI on or off. | changes |
| Make a mob attack an entity, or clear its target. | changes |
| Items in an entity's armour and hand slots. | read-only |
| Equip a mob or armor stand, with optional drop chances. | destructive |
| Hurt a living entity. | destructive |
| Make one entity ride another, or dismount it. | changes |
| Base and effective value of an attribute, e.g. | read-only |
| Set an attribute's base value, e.g. | changes |
| An entity's scoreboard tags. | read-only |
| Add and remove scoreboard tags. | changes |
| A villager's profession, level and trades. | read-only |
| Change a villager's profession, which resets its trades. | destructive |
| Replace all of a villager's trades. | destructive |
chat
Tool | What it does | Access |
| Send a chat message to every player. | changes |
| Send a private message to one player. | changes |
| Send formatted, clickable text with | changes |
| Show a title and subtitle on a player's screen. | changes |
| Play a sound to a player. | changes |
| Stop one sound, or all sounds, for a player. | changes |
| Show particles at a position. | changes |
scoreboard
Tool | What it does | Access |
| Create a scoreboard objective. | changes |
| Delete an objective and all of its scores. | destructive |
| Show an objective in the sidebar, below names or in the list, or clear a slot. | changes |
| Set a score, replacing the previous value. | destructive |
| Read a score. | read-only |
| All teams with display names and members. | read-only |
| Create a team. | changes |
| Delete a team. | destructive |
| Add and remove team members. | changes |
| Change a team option such as colour or friendly fire. | changes |
| Boss bars created through MCPyLib, with their settings and viewers. | read-only |
| Create a boss bar and show it to players. | changes |
| Change a boss bar's title, colour, style, progress or viewers. | changes |
| Delete a boss bar. | destructive |
The layers format
get_blocks (with the default layout="layers") and build_from_layers share one format:
Palette: maps single characters to blocks.
Layers: a list of horizontal slices, ordered bottom to top.
Each slice is a list of rows, ordered north to south.
Each row is a string read west to east, one character per block.
Special characters:
.is air and a space leaves the existing block unchanged.
This call builds a 3x3 stone-brick ring with a glass ring on top:
{
"x": 100, "y": 64, "z": -20,
"palette": { "#": "stone_bricks", "G": "glass" },
"layers": [
["###", "#.#", "###"],
["#G#", "G.G", "#G#"]
]
}A palette entry can also be an object with a block state, for example
{"block": "oak_door", "block_state": {"half": "lower", "facing": "south"}}. The
minecraft://guide/building resource explains the format and a building workflow in more detail.
Resources and prompts
Resource | Contents |
| Connection state, online players, time of day, world border, and this server's limits and enabled tools. It reports |
| An online player's UUID, game mode, position and experience. |
| Coordinates, block states, the layers format and a building workflow (Markdown). |
Prompt | What it does |
| Plans and builds a described structure. It surveys the site, prepares the ground, builds in sections, verifies the result and reports. Hidden when the tools it needs are disabled, as in read-only mode. |
| Inspects an area without changing it: terrain heights, materials, water, player builds and good building spots. |
Safety
The MCPyLib token gives full control of the Minecraft server. Treat this MCP server as an operator account.
Per-call block limit.
MCPYLIB_MAX_BLOCKS(default 100,000) caps the region of every block tool:get_blocks,get_height_map,fill_region,clone_region,edit_blocks,build_from_layersandfill_biome. The size is checked before anything is sent, so an over-sized request never reaches Minecraft and the agent is told to split the work. The limit does not coverrun_command, or world generation (place_structureand the otherplace_*tools), whose size the game decides.Read-only mode.
--read-onlyorMCPYLIB_READ_ONLY=trueregisters only the 21 read-only tools. Write tools are not just refused: the client never sees them. Allowlists cannot add write tools back.Allowlists and denylists. They are applied when the server starts. An entry that matches no tool is a startup error, so a typo such as
run_comandcan never silently leave a tool enabled. Use--list-toolsto preview the result.run_commandruns any console command, including/stopand/op, and bypasses the limits above. Deny it (MCPYLIB_DENIED_TOOLS=run_command) if you want the other safety settings to mean something.Annotations. Every tool declares MCP annotations:
readOnlyHint,destructiveHint,idempotentHintandopenWorldHint: false. Clients that honour them can auto-approve read-only tools and ask before destructive ones. Keep approval prompts on for destructive tools when working on a world you care about.Token handling. Keep the token in
MCPYLIB_TOKENrather than--token, because other local users can read command lines. The server never logs it: settings print it as***and log output is filtered as a second line of defence. If a token leaks, replace it with/mcpylib token regenerate, then update your MCP configuration.HTTP transport. The HTTP endpoint has no authentication. By default it binds to
127.0.0.1, and the MCP SDK then also enables DNS-rebinding protection. Binding to another address logs a warning, because anyone who can reach the port can control your Minecraft server. To serve it remotely, put it behind an authenticating reverse proxy, VPN or SSH tunnel.Retries. If the plugin does not answer in time, mcpylib retries the command once. After a timeout, a non-idempotent action such as
give_itemmay therefore have happened twice. Check before repeating it.Connections. Each mcpylib-mcp process keeps one connection to the plugin. The plugin accepts
server.max-connectionsconnections at a time (default 10).
Troubleshooting
Message | What to do |
| Set |
| The token is wrong or was regenerated. Run |
| Check that the Minecraft server is running, the plugin is loaded, |
| The server is busy or the request is large. Use smaller regions, or raise |
| Split the region into smaller parts. Only raise |
The client shows no tools | Run the command from your configuration in a terminal with |
Set MCPYLIB_LOG_LEVEL=DEBUG to see each call to the plugin in the client's MCP log.
The mcpylib dependency
This server talks to the plugin through MCPyLib's Python client, mcpylib,
and depends on mcpylib>=1.1.1 from PyPI.
Why 1.1.1: it is the first release with everything the tools use, namely the persistent connection and
getblocks. It is on PyPI, souvx --from git+...,pip installanduvresolve it today without extra indexes or git URLs.Why not a git dependency: depending on MCPyLib's repository directly would block a future PyPI release of this package, because PyPI rejects packages whose dependencies are direct URLs. Its client also lives in a subdirectory of that repository.
When mcpylib 1.2.0 is published: new installs pick it up automatically, and nothing here needs to change.
Plugin compatibility: mcpylib 1.1.1 works with MCPyLib plugins 1.1.2 and 1.2.0. mcpylib 1.2.0 sends bulk edits only in a new compressed form, which needs plugin 1.2.0 or newer for
edit_blocksandbuild_from_layers. The plugin build for Minecraft 26.1+ is 1.2.0, so keep the plugin up to date.
Development
git clone https://github.com/treeleaves30760/MCPyLib-mcp
cd MCPyLib-mcp
uv sync # create .venv with the dev tools
uv run pytest # tests run against a fake in-process MCPyLib plugin
uv run ruff check . && uv run ruff format --check .
uv run mcpylib-mcp --list-toolsThe tests need no Minecraft server. tests/fake_server.py speaks the MCPyLib protocol over TCP, and the
suite drives the real MCP server in-process, over stdio and over HTTP.
Project layout:
src/mcpylib_mcp/tools/defines one module per tool group.bridge.pyserialises plugin calls and translates errors.safety.pyholds the block limit and tool filtering.encoding.pyimplements the layers format.
Related projects
MCPyLib: the Python library and the Spigot/Paper plugin.
MCPyLib-skills: Agent Skills that teach AI coding agents the MCPyLib API, building recipes and mini-game patterns.
MCPyLib website: documentation and showcase.
License
MCPyLib Non-Commercial License, the same license as MCPyLib. Non-commercial use only; read the license for details.
Available Tools
86 toolsapply_effectApply status effectBIdempotent
Give an online player a status effect such as speed, night_vision or regeneration.
Inputs: effect (required), username (required), amplifier, hide_particles, +1 more. Returns: object
broadcast_messageBroadcast messageA
Send a chat message to every player; it appears as '[Server] '.
Inputs: message (required). Returns: object
build_from_layersBuild from text layersADestructiveIdempotent
Build a structure from text layers, like floor plans stacked bottom to top: character k of row j of layer i becomes block (x + k, y + i, z + j). Ideal for houses, statues and pixel art; use fill_region for big solid volumes. get_blocks returns this same format, so a region can be read, edited and written back. Refuses structures whose bounding box exceeds 100,000 blocks.
Example: palette {"#": "stone_bricks", "G": "glass", ".": "air"} with layers [["###", "#.#", "###"], ["#G#", "G.G", "#G#"]] builds a 3x3 stone ring with a glass ring on top.
Inputs: x (required), y (required), z (required), layers (required), +1 more. Returns: object
clear_effectsClear status effectsAIdempotent
Remove one or all status effects from an online player.
Inputs: username (required), effect. Returns: object
clear_inventoryClear inventoryADestructive
Remove items from an online player's inventory (all items, or only one item type).
Inputs: username (required), item, max_count. Returns: object
clone_regionClone a boxADestructiveIdempotent
Copy a box of blocks (types and states) so that its lowest corner lands at (dest_x, dest_y, dest_z), overwriting the destination. Container contents and sign text are not copied. Source and destination must not overlap. At most 32,768 blocks (plugin limit) and at most 100,000.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +5 more. Returns: object
create_bossbarCreate boss barA
Create a boss bar and show it to the given players. Bars live in the plugin's memory: they are separate from vanilla /bossbar and disappear when the server restarts.
Inputs: bar_id (required), color, style, title, +3 more. Returns: object
create_objectiveCreate objectiveA
Create a scoreboard objective (fails if it already exists).
Inputs: name (required), criteria, display_name. Returns: object
create_teamCreate teamA
Create a scoreboard team (fails if it already exists).
Inputs: name (required), display_name. Returns: object
damage_entityDamage entityADestructive
Hurt a living entity. Enough damage kills it.
Inputs: uuid (required), amount (required), source_uuid. Returns: object
edit_blocksEdit blocks from a 3D arrayADestructiveIdempotent
Place many different blocks in one call from a 3D array (MCPyLib's bulk edit). build_from_layers is usually easier to write. Refuses arrays whose bounding box exceeds 100,000 blocks.
Inputs: x (required), y (required), z (required), blocks (required). Returns: object
enchant_held_itemEnchant held itemAIdempotent
Add an enchantment to the item in an online player's main hand (fails if the hand is empty).
Inputs: username (required), enchantment (required), level. Returns: object
fill_biomeFill biomeADestructiveIdempotent
Change the biome of a box in the main world (affects grass/water colour, weather and mob spawns; players may need to rejoin to see colours change). Refuses boxes over 100,000 blocks; the plugin only reports whether the vanilla /fillbiome command was dispatched.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +4 more. Returns: object
fill_regionFill a boxADestructiveIdempotent
Fill a box (corners inclusive, any order) with one block, replacing everything inside; use 'air' to clear an area. Refuses boxes larger than 100,000 blocks. Blocks are placed without physics, so sand does not fall and water does not flow until neighbours update.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +3 more. Returns: object
get_advancementCheck advancementBRead-onlyIdempotent
Whether an online player has completed an advancement.
Inputs: username (required), advancement (required). Returns: object
get_blockGet blockARead-onlyIdempotent
Return the block id at one position, e.g. 'minecraft:stone' (block states are not included).
Inputs: x (required), y (required), z (required). Returns: object
get_blocksRead blocks in a boxARead-onlyIdempotent
Read every block in a box (corners inclusive, any order; at most 100,000 blocks).
The default 'layers' layout returns palette (character -> block id) and layers: one entry per Y
from the bottom up, each a list of row strings from north to south (+Z), each row read west to east
(+X). '.' is air. It is the exact input format of build_from_layers, so you can edit the strings and
write them back. counts gives the number of each block. Keep raw reads small (16x16x16 is plenty);
use layout='summary' or get_height_map for big areas.
Inputs: x1 (required), x2 (required), y1 (required), y2 (required), +3 more. Returns: object
get_chunk_force_loadedCheck chunk force-loadingBRead-onlyIdempotent
Whether the chunk containing block (x, z) of the main world is force-loaded.
Inputs: x (required), z (required). Returns: object
get_entityGet entityBRead-onlyIdempotent
Details of one entity: type, custom name, world, position, rotation, velocity, health and AI state.
Inputs: uuid (required). Returns: object
get_entity_attributeGet entity attributeBRead-onlyIdempotent
Base and effective value of a living entity's attribute (e.g. max_health, movement_speed).
Inputs: uuid (required), attribute (required). Returns: object
get_entity_equipmentGet entity equipmentBRead-onlyIdempotent
Items in a living entity's armour and hand slots (null for empty slots).
Inputs: uuid (required). Returns: object
get_entity_tagsGet entity tagsBRead-onlyIdempotent
An entity's scoreboard tags: labels usable in selectors such as @e[tag=boss].
Inputs: uuid (required). Returns: object
get_experienceGet experienceBRead-onlyIdempotent
An online player's experience: level, total points and progress (0-1) toward the next level.
Inputs: username (required). Returns: object
get_gameruleGet game ruleBRead-onlyIdempotent
Current value of a game rule in the main world, as a string.
Inputs: rule (required). Returns: object
get_height_mapMap surface heightsARead-onlyIdempotent
Find the ground: for each column of an X/Z area, the Y of the highest block that is not air.
heights[z][x] is an absolute Y (null for an empty column): rows go north to south (+Z), entries west
to east (+X). surface uses the same layout with characters from surface_palette. Build on a column
at heights + 1. Scans (area x height) blocks, at most 100,000; narrow y_min/y_max for big areas.
Inputs: x1 (required), x2 (required), z1 (required), z2 (required), +3 more. Returns: object
get_inventoryGet inventoryARead-onlyIdempotent
List the non-empty inventory slots of an online player, with item, amount and enchantments. Slots: 0-8 hotbar, 9-35 main, 36 boots, 37 leggings, 38 chestplate, 39 helmet, 40 off-hand.
Inputs: username (required), slots. Returns: object
get_player_positionGet player positionARead-onlyIdempotent
Block position of an online player's feet (rounded down); the block they stand on is at y - 1.
Inputs: username (required). Returns: object
get_playersList online playersARead-onlyIdempotent
List the players currently online (name, UUID, game mode) and the server's player limit.
Inputs: no named parameters. Returns: object
get_scoreGet scoreBRead-onlyIdempotent
A score holder's score on an objective (0 if they have none).
Inputs: player (required), objective (required). Returns: object
get_timeGet time of dayARead-onlyIdempotent
Current time of day in the main world: ticks (0-23999), phase (day/sunset/night/sunrise) and clock.
Inputs: no named parameters. Returns: object
get_villagerGet villagerCRead-onlyIdempotent
A villager's profession, level and trades (with uses and limits).
Inputs: uuid (required). Returns: object
get_world_borderGet world borderBRead-onlyIdempotent
The main world's border: size (diameter), centre, damage and warning settings.
Inputs: no named parameters. Returns: object
give_itemGive itemA
Add items to an online player's inventory. Items that do not fit are lost.
Inputs: item (required), username (required), amount. Returns: object
kill_entitiesKill entitiesADestructiveIdempotent
Remove entities from the main world (at most 1,000 per call). Mobs are removed without drops; a killed player dies normally and drops their items. 'all' removes EVERY non-player entity, including pets, villagers, item frames, armor stands, paintings, boats and minecarts: prefer a specific type, or remove_entity for one entity.
Inputs: target (required). Returns: object
list_bossbarsList boss barsBRead-onlyIdempotent
Boss bars created through MCPyLib, with title, colour, style, progress, visibility and viewers.
Inputs: no named parameters. Returns: object
list_teamsList teamsARead-onlyIdempotent
All scoreboard teams with their display names and members.
Inputs: no named parameters. Returns: object
locate_structureLocate structureARead-onlyIdempotent
Find the nearest structure of a type in the main world, searching up to 100 chunks out. Can take a few seconds and may generate chunks.
Inputs: structure (required), x, z. Returns: object
place_featurePlace featureADestructive
Generate a configured feature (tree, ore vein, dungeon, ...) like world generation does. Without coordinates it is placed at world spawn. Only whether the command was dispatched is reported.
Inputs: feature (required), x, y, z. Returns: object
place_jigsawPlace jigsaw structureBDestructive
Generate a jigsaw structure from a template pool. Without coordinates it is placed at world spawn. Only dispatch is reported.
Inputs: pool (required), target (required), max_depth (required), x, +2 more. Returns: object
place_structurePlace structureADestructive
Generate a whole structure (village, temple, ...) like world generation does; it can be large and overwrites terrain. Without coordinates it is placed at world spawn. Only dispatch is reported.
Inputs: structure (required), x, y, z. Returns: object
place_templatePlace structure templateADestructiveIdempotent
Place a saved structure template (structure block / NBT file) with its lowest corner at (x, y, z). Only dispatch is reported; verify with get_blocks.
Inputs: x (required), y (required), z (required), template (required), +4 more. Returns: object
play_soundPlay soundA
Play a sound to one online player, at a position or (by default) at the player.
Inputs: sound (required), username (required), x, y, +4 more. Returns: object
remove_bossbarRemove boss barBDestructiveIdempotent
Delete a boss bar and hide it from everyone.
Inputs: bar_id (required). Returns: object
remove_entityRemove entityADestructiveIdempotent
Delete one entity (not a player) without drops or death animation.
Inputs: uuid (required). Returns: object
remove_objectiveRemove objectiveADestructiveIdempotent
Delete a scoreboard objective and all of its scores.
Inputs: name (required). Returns: object
remove_teamRemove teamADestructiveIdempotent
Delete a scoreboard team; its members become teamless.
Inputs: name (required). Returns: object
ride_entityMount or dismountBIdempotent
Make one entity ride another, or dismount it.
Inputs: passenger_uuid (required), vehicle_uuid. Returns: object
run_commandRun a console commandADestructive
Run any Minecraft command as the server console.
Unrestricted escape hatch: it can do anything an operator can, including stopping the server, and the per-call block limit does not apply. Prefer the dedicated tools. The plugin only reports whether the command was dispatched; the command's output is not returned.
Inputs: command (required). Returns: object
send_messageMessage a playerA
Send a private chat message to one online player.
Inputs: message (required), username (required). Returns: object
send_rich_messageSend formatted messageA
Send a formatted (coloured, clickable, hoverable) chat message using vanilla /tellraw.
Inputs: text (required), target (required). Returns: object
set_advancementGrant or revoke advancementBDestructiveIdempotent
Grant or revoke an advancement for an online player.
Inputs: granted (required), username (required), advancement (required). Returns: object
set_blockSet blockADestructiveIdempotent
Place one block, replacing what is there. For more than a handful of blocks use fill_region or build_from_layers. Doors and beds need both halves placed explicitly.
Inputs: x (required), y (required), z (required), block (required), +2 more. Returns: object
set_chunk_force_loadedForce-load chunkAIdempotent
Keep (or stop keeping) the chunk containing block (x, z) of the main world loaded, so redstone and farms there run without players nearby.
Inputs: x (required), z (required), force_loaded (required). Returns: object
set_default_gamemodeSet default game modeAIdempotent
Set the game mode that players get when they first join.
Inputs: mode (required). Returns: object
set_difficultySet difficultyAIdempotent
Change the difficulty of the main world. 'peaceful' removes hostile mobs.
Inputs: level (required). Returns: object
set_entity_aiEnable or disable entity AIBIdempotent
Turn a mob's AI on or off (living entities only).
Inputs: uuid (required), enabled (required). Returns: object
set_entity_attributeSet entity attributeBIdempotent
Set the base value of a living entity's attribute, e.g. max_health 40 or scale 2.
Inputs: uuid (required), attribute (required), base_value (required). Returns: object
set_entity_equipmentSet entity equipmentADestructiveIdempotent
Equip a living entity (mob or armor stand); slots you omit are left unchanged, and the replaced items are lost.
Inputs: uuid (required), boots, helmet, leggings, +4 more. Returns: object
set_entity_rotationSet entity rotationAIdempotent
Turn an entity to face a direction without moving it.
Inputs: yaw (required), uuid (required), pitch (required). Returns: object
set_entity_targetSet mob targetAIdempotent
Make a mob attack a specific living entity, or clear its target.
Inputs: uuid (required), target_uuid. Returns: object
set_entity_velocitySet entity velocityAIdempotent
Push an entity: set its velocity vector (e.g. vy=1 for a jump of about 7 blocks).
Inputs: vx (required), vy (required), vz (required), uuid (required). Returns: object
set_gamemodeSet game modeAIdempotent
Change an online player's game mode (survival, creative, adventure or spectator).
Inputs: mode (required), username (required). Returns: object
set_gameruleSet game ruleAIdempotent
Set a boolean or integer game rule in the main world and return the value the server now reports (check it: the plugin silently ignores values it cannot parse).
Inputs: rule (required), value (required). Returns: object
set_inventory_slotSet inventory slotBDestructiveIdempotent
Put an item stack into one inventory slot, replacing whatever was there.
Inputs: item (required), slot (required), username (required), amount. Returns: object
set_objective_displayShow objectiveAIdempotent
Show an objective in the sidebar, below player names or in the player list, or clear that slot.
Inputs: slot (required), objective. Returns: object
set_scoreSet scoreADestructiveIdempotent
Set a score holder's score on an objective, replacing the previous value.
Inputs: score (required), player (required), objective (required). Returns: object
set_spawnpointSet spawn pointAIdempotent
Set where an online player respawns: the given position, or where they stand now.
Inputs: username (required), x, y, z. Returns: object
set_team_optionSet team optionBIdempotent
Change a team setting such as its colour or friendly fire.
Inputs: name (required), value (required), option (required). Returns: object
set_timeSet time of dayA
Set or advance the time of day in the main world.
Inputs: value (required), mode. Returns: object
set_villager_professionSet villager professionADestructiveIdempotent
Change a villager's profession. This resets the villager's current trades.
Inputs: uuid (required), profession (required). Returns: object
set_villager_tradesSet villager tradesADestructiveIdempotent
Replace all of a villager's trades with custom ones.
Inputs: uuid (required), trades (required). Returns: object
set_weatherSet weatherAIdempotent
Change the weather in the main world to clear, rain or thunder, optionally for a set duration.
Inputs: condition (required), duration_seconds. Returns: object
set_world_borderChange world borderA
Change any combination of the main world's border settings in one call; omitted settings are left alone. Returns the resulting border.
Inputs: size, grow_by, center_x, center_z, +4 more. Returns: object
set_world_spawnSet world spawnBIdempotent
Set the main world's spawn point (where new players appear and compasses point).
Inputs: x (required), y (required), z (required). Returns: object
show_titleShow titleB
Show a big title and/or subtitle in the middle of an online player's screen.
Inputs: username (required), stay, title, fade_in, +2 more. Returns: object
spawn_lootDrop lootA
Roll a loot table once and drop the resulting items at a position in the main world.
Inputs: x (required), y (required), z (required), loot_table (required). Returns: object
spawn_particlesSpawn particlesB
Show particles at a position in the main world (visible to nearby players).
Inputs: x (required), y (required), z (required), particle (required), +5 more. Returns: object
spread_playersSpread playersA
Teleport players to random surface positions around a centre point (vanilla /spreadplayers).
Inputs: center_x (required), center_z (required), max_range (required), usernames (required), +1 more. Returns: object
stop_soundStop soundsAIdempotent
Stop sounds playing for an online player: one sound, or everything.
Inputs: username (required), sound, source. Returns: object
summon_entitySummon entityA
Spawn an entity in the main world and return its UUID (used by every other entity tool).
Inputs: x (required), y (required), z (required), entity_type (required). Returns: object
teleport_entityTeleport entityCIdempotent
Move an entity to an exact position, optionally setting where it faces.
Inputs: x (required), y (required), z (required), uuid (required), +2 more. Returns: object
teleport_playerTeleport playerAIdempotent
Teleport an online player within their current world, optionally setting where they face.
Inputs: x (required), y (required), z (required), username (required), +2 more. Returns: object
update_bossbarUpdate boss barAIdempotent
Change a boss bar's look or progress and who sees it; omitted settings are left alone.
Inputs: bar_id (required), color, style, title, +4 more. Returns: object
update_entity_tagsAdd or remove entity tagsAIdempotent
Add and/or remove scoreboard tags on an entity and return its resulting tags.
Inputs: uuid (required), add, remove. Returns: object
update_experienceChange experienceA
Add or set an online player's experience. Note: mode='set' with unit='points' sets the progress bar within the current level (amount / points needed for the next level), not the total points.
Inputs: amount (required), username (required), mode, unit. Returns: object
update_team_membersChange team membersAIdempotent
Add and/or remove team members (a player can only be in one team; joining moves them).
Inputs: name (required), add, remove. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 86 tools
Most tools target clearly distinct Minecraft resources and actions, with descriptions giving useful selection guidance. There is some overlap among bulk world-editing tools (set_block, fill_region, edit_blocks, build_from_layers, clone_region) and among structure/feature placement tools, but these boundaries are mostly explained. run_command is a deliberate escape hatch, which adds some ambiguity but is explicitly framed as a fallback.
Tool names are consistently snake_case and predominantly follow verb_noun or get/set resource patterns. Minor inconsistencies such as get_* versus list_* for collections and a few longer descriptive names are still readable and semantically predictable. No chaotic mixing of camelCase or arbitrary naming styles.
With 86 tools, the surface is far beyond a practical tool set for an agent and greatly exceeds the typical 3-15 range. Although the Minecraft server domain is broad and each tool may have a use, the result is an unwieldy catalog with many operations that could be consolidated or reached through run_command.
Coverage is very broad: players, blocks, entities, world settings, inventory, effects, scoreboard, teams, boss bars, chat, sounds and particles are all represented. There are minor gaps such as no obvious list/get for scoreboard objectives and no general entity listing/querying beyond known IDs, but most core workflows are supported.
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
An MCP server that gives your AI access to the source code and docs of all public github repos
Connect AI agents to Flato's editable canvas runtime through a hosted MCP server.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control a Minecraft bot for movement, building, crafting, and instant schematic-based structure spawning via MCP tools.2Apache 2.0
- AlicenseNot gradedqualityFmaintenanceEnables AI agents to communicate, coordinate, and collaborate on complex tasks through a local MCP server.8Business Source 1.1
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Minecraft via MCP with configurable versions, creative building commands, survival helpers, and an autonomous agent loop.Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to control a Minecraft bot inside a Java Edition world via MCP, providing tools for movement, building, mining, combat, farming, trading, inventory, and world perception.551MIT