Skip to main content
Glama

MCPyLib-mcp

CI

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/Spigot

Once 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_blocks returns a region as text layers (floor plans stacked bottom to top). build_from_layers accepts the same format, so an agent can read, edit and write back a build. get_height_map finds 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

  1. Install the plugin. Put the MCPyLib plugin jar from the MCPyLib releases into the server's plugins/ folder and restart the server.

  2. Get a token. Run /mcpylib token in the server console, or in game with the mcpylib.admin permission. Copy the token it prints.

  3. 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-tools
  4. Add 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-mcp
  • Remote server: add -e MCPYLIB_HOST=192.168.1.20.

  • All projects: add --scope user before mcpylib.

  • Check the connection: run claude mcp list or use /mcp in 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

  1. Open the config file with Settings > Developer > Edit Config. The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows.

  2. 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"
          }
        }
      }
    }
  3. 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 8000

In 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/mcp

  • VS 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

MCPYLIB_TOKEN

--token

required

Token printed by /mcpylib token. Prefer the variable, because other local users can see command lines.

MCPYLIB_HOST

--mc-host

localhost

Host of the Minecraft server that runs the MCPyLib plugin.

MCPYLIB_PORT

--mc-port

65535

Plugin port (server.port in plugins/MCPyLib/config.yml).

MCPYLIB_TIMEOUT

--timeout

30

Seconds to wait for each reply from the plugin.

MCPYLIB_MAX_BLOCKS

--max-blocks

100000

The most blocks one tool call may read or change.

MCPYLIB_READ_ONLY

--read-only / --no-read-only

false

Register only tools that do not change the world.

MCPYLIB_ALLOWED_TOOLS

--allow-tools

all tools

Register only these tools. Entries are names, globs (get_*) or groups (group:blocks).

MCPYLIB_DENIED_TOOLS

--deny-tools

none

Never register these tools. Same syntax; the denylist wins over the allowlist.

MCPYLIB_TRANSPORT

--transport

stdio

stdio, or http for streamable HTTP.

MCPYLIB_HTTP_HOST

--host

127.0.0.1

Address the HTTP transport binds to.

MCPYLIB_HTTP_PORT

--port

8000

Port of the HTTP transport. The endpoint is /mcp.

MCPYLIB_LOG_LEVEL

--log-level

INFO

DEBUG, INFO, WARNING, ERROR or CRITICAL. Logs go to stderr.

  • --mc-host and --mc-port point at Minecraft. --host and --port configure the MCP HTTP transport.

  • Lists are separated by commas or spaces. Booleans accept true/false, 1/0, yes/no and on/off.

  • --list-tools prints the tools your settings enable and exits. It needs no token, so it is a quick way to check a filter. --version and --help work 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-mcp

Tools

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

get_players

List online players (name, UUID, game mode) and the player limit.

read-only

run_command

Run any Minecraft command as the server console. The block limit does not apply; see Safety.

destructive

blocks

Tool

What it does

Access

get_block

Return the block id at one position, e.g. minecraft:stone.

read-only

get_blocks

Read every block in a box, as text layers, an index array or block counts.

read-only

get_height_map

For each column of an area, the Y of the highest non-air block, optionally ignoring leaves or plants.

read-only

set_block

Place one block, with optional block state and sign text, replacing what is there.

destructive

fill_region

Fill a box with one block; use air to clear an area.

destructive

clone_region

Copy a box of blocks to another place (at most 32,768 blocks, a plugin limit).

destructive

edit_blocks

Place many different blocks in one call from a 3D array (MCPyLib's bulk edit).

destructive

build_from_layers

Build from text layers: floor plans stacked bottom to top, each character one block.

destructive

players

Tool

What it does

Access

get_player_position

Block position of an online player's feet.

read-only

teleport_player

Teleport a player, optionally setting where they face.

changes

set_gamemode

Set a player's game mode.

changes

give_item

Add items to a player's inventory.

changes

get_inventory

List a player's non-empty inventory slots with items, amounts and enchantments.

read-only

set_inventory_slot

Put an item stack into one slot, replacing what was there.

destructive

clear_inventory

Remove all items, or one item type, from a player's inventory.

destructive

enchant_held_item

Enchant the item in a player's main hand.

changes

apply_effect

Give a player a status effect such as speed or night vision.

changes

clear_effects

Remove one or all status effects.

changes

get_experience

A player's level, points and progress to the next level.

read-only

update_experience

Add or set experience points or levels.

changes

set_spawnpoint

Set where a player respawns.

changes

get_advancement

Whether a player has completed an advancement.

read-only

set_advancement

Grant or revoke an advancement.

destructive

spread_players

Teleport players to random surface positions around a point (/spreadplayers).

changes

world

Tool

What it does

Access

get_time

Time of day: ticks, phase (day, sunset, night, sunrise) and clock time.

read-only

set_time

Set or advance the time, by preset (day, noon, night...) or ticks.

changes

set_weather

Clear, rain or thunder, optionally for a duration.

changes

set_difficulty

Set the difficulty.

changes

get_gamerule

Current value of a game rule.

read-only

set_gamerule

Set a game rule and return the value the server now reports.

changes

set_world_spawn

Set the world spawn point.

changes

set_default_gamemode

Set the game mode new players get.

changes

get_world_border

The world border's size, centre, damage and warning settings.

read-only

set_world_border

Change any combination of world-border settings in one call.

changes

get_chunk_force_loaded

Whether the chunk containing a block is force-loaded.

read-only

set_chunk_force_loaded

Force-load a chunk, or stop force-loading it.

changes

fill_biome

Change the biome of a box.

destructive

locate_structure

Find the nearest structure of a type, such as a village.

read-only

place_feature

Generate a feature (tree, ore vein...) as world generation does.

destructive

place_structure

Generate a whole structure (village, temple...).

destructive

place_jigsaw

Generate a jigsaw structure from a template pool.

destructive

place_template

Place a saved structure template.

destructive

spawn_loot

Roll a loot table and drop the items at a position.

changes

entities

Tool

What it does

Access

summon_entity

Spawn an entity and return its UUID, which the other entity tools use.

changes

kill_entities

Remove entities by type, a player, or all non-player entities (at most 1,000 per call).

destructive

remove_entity

Delete one entity without drops.

destructive

get_entity

An entity's type, name, position, rotation, velocity, health and AI state.

read-only

teleport_entity

Move an entity to an exact position.

changes

set_entity_velocity

Push an entity by setting its velocity vector.

changes

set_entity_rotation

Turn an entity without moving it.

changes

set_entity_ai

Turn a mob's AI on or off.

changes

set_entity_target

Make a mob attack an entity, or clear its target.

changes

get_entity_equipment

Items in an entity's armour and hand slots.

read-only

set_entity_equipment

Equip a mob or armor stand, with optional drop chances.

destructive

damage_entity

Hurt a living entity.

destructive

ride_entity

Make one entity ride another, or dismount it.

changes

get_entity_attribute

Base and effective value of an attribute, e.g. max_health.

read-only

set_entity_attribute

Set an attribute's base value, e.g. scale 2.

changes

get_entity_tags

An entity's scoreboard tags.

read-only

update_entity_tags

Add and remove scoreboard tags.

changes

get_villager

A villager's profession, level and trades.

read-only

set_villager_profession

Change a villager's profession, which resets its trades.

destructive

set_villager_trades

Replace all of a villager's trades.

destructive

chat

Tool

What it does

Access

broadcast_message

Send a chat message to every player.

changes

send_message

Send a private message to one player.

changes

send_rich_message

Send formatted, clickable text with /tellraw.

changes

show_title

Show a title and subtitle on a player's screen.

changes

play_sound

Play a sound to a player.

changes

stop_sound

Stop one sound, or all sounds, for a player.

changes

spawn_particles

Show particles at a position.

changes

scoreboard

Tool

What it does

Access

create_objective

Create a scoreboard objective.

changes

remove_objective

Delete an objective and all of its scores.

destructive

set_objective_display

Show an objective in the sidebar, below names or in the list, or clear a slot.

changes

set_score

Set a score, replacing the previous value.

destructive

get_score

Read a score.

read-only

list_teams

All teams with display names and members.

read-only

create_team

Create a team.

changes

remove_team

Delete a team.

destructive

update_team_members

Add and remove team members.

changes

set_team_option

Change a team option such as colour or friendly fire.

changes

list_bossbars

Boss bars created through MCPyLib, with their settings and viewers.

read-only

create_bossbar

Create a boss bar and show it to players.

changes

update_bossbar

Change a boss bar's title, colour, style, progress or viewers.

changes

remove_bossbar

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

minecraft://server/status

Connection state, online players, time of day, world border, and this server's limits and enabled tools. It reports connected: false with the reason when the plugin is unreachable.

minecraft://players/{username}

An online player's UUID, game mode, position and experience.

minecraft://guide/building

Coordinates, block states, the layers format and a building workflow (Markdown).

Prompt

What it does

build_structure

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.

survey_area

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_layers and fill_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 cover run_command, or world generation (place_structure and the other place_* tools), whose size the game decides.

  • Read-only mode. --read-only or MCPYLIB_READ_ONLY=true registers 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_comand can never silently leave a tool enabled. Use --list-tools to preview the result.

  • run_command runs any console command, including /stop and /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, idempotentHint and openWorldHint: 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_TOKEN rather 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_item may therefore have happened twice. Check before repeating it.

  • Connections. Each mcpylib-mcp process keeps one connection to the plugin. The plugin accepts server.max-connections connections at a time (default 10).

Troubleshooting

Message

What to do

no MCPyLib token configured

Set MCPYLIB_TOKEN in the client's env block.

Authentication failed ... rejected the token

The token is wrong or was regenerated. Run /mcpylib token to see the current token and update the configuration.

Cannot reach the MCPyLib plugin at host:port

Check that the Minecraft server is running, the plugin is loaded, MCPYLIB_HOST/MCPYLIB_PORT are right, and no firewall blocks the port.

Timed out after 30s ...

The server is busy or the request is large. Use smaller regions, or raise MCPYLIB_TIMEOUT.

... more than the per-call limit ...

Split the region into smaller parts. Only raise MCPYLIB_MAX_BLOCKS if a change that large is really intended.

The client shows no tools

Run the command from your configuration in a terminal with --list-tools, and check your allow/deny settings. For Claude Desktop, check that uvx is found (use its full path).

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, so uvx --from git+..., pip install and uv resolve 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_blocks and build_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-tools

The 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.py serialises plugin calls and translates errors.

  • safety.py holds the block limit and tool filtering.

  • encoding.py implements the layers format.

  • 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 tools
apply_effectApply status effectB
Idempotent

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 layersA
DestructiveIdempotent

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 effectsA
Idempotent

Remove one or all status effects from an online player.

Inputs: username (required), effect. Returns: object

clear_inventoryClear inventoryA
Destructive

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 boxA
DestructiveIdempotent

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 entityA
Destructive

Hurt a living entity. Enough damage kills it.

Inputs: uuid (required), amount (required), source_uuid. Returns: object

edit_blocksEdit blocks from a 3D arrayA
DestructiveIdempotent

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 itemA
Idempotent

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 biomeA
DestructiveIdempotent

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 boxA
DestructiveIdempotent

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 advancementB
Read-onlyIdempotent

Whether an online player has completed an advancement.

Inputs: username (required), advancement (required). Returns: object

get_blockGet blockA
Read-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 boxA
Read-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-loadingB
Read-onlyIdempotent

Whether the chunk containing block (x, z) of the main world is force-loaded.

Inputs: x (required), z (required). Returns: object

get_entityGet entityB
Read-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 attributeB
Read-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 equipmentB
Read-onlyIdempotent

Items in a living entity's armour and hand slots (null for empty slots).

Inputs: uuid (required). Returns: object

get_entity_tagsGet entity tagsB
Read-onlyIdempotent

An entity's scoreboard tags: labels usable in selectors such as @e[tag=boss].

Inputs: uuid (required). Returns: object

get_experienceGet experienceB
Read-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 ruleB
Read-onlyIdempotent

Current value of a game rule in the main world, as a string.

Inputs: rule (required). Returns: object

get_height_mapMap surface heightsA
Read-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 inventoryA
Read-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 positionA
Read-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 playersA
Read-onlyIdempotent

List the players currently online (name, UUID, game mode) and the server's player limit.

Inputs: no named parameters. Returns: object

get_scoreGet scoreB
Read-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 dayA
Read-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 villagerC
Read-onlyIdempotent

A villager's profession, level and trades (with uses and limits).

Inputs: uuid (required). Returns: object

get_world_borderGet world borderB
Read-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 entitiesA
DestructiveIdempotent

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 barsB
Read-onlyIdempotent

Boss bars created through MCPyLib, with title, colour, style, progress, visibility and viewers.

Inputs: no named parameters. Returns: object

list_teamsList teamsA
Read-onlyIdempotent

All scoreboard teams with their display names and members.

Inputs: no named parameters. Returns: object

locate_structureLocate structureA
Read-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 featureA
Destructive

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 structureB
Destructive

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 structureA
Destructive

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 templateA
DestructiveIdempotent

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 barB
DestructiveIdempotent

Delete a boss bar and hide it from everyone.

Inputs: bar_id (required). Returns: object

remove_entityRemove entityA
DestructiveIdempotent

Delete one entity (not a player) without drops or death animation.

Inputs: uuid (required). Returns: object

remove_objectiveRemove objectiveA
DestructiveIdempotent

Delete a scoreboard objective and all of its scores.

Inputs: name (required). Returns: object

remove_teamRemove teamA
DestructiveIdempotent

Delete a scoreboard team; its members become teamless.

Inputs: name (required). Returns: object

ride_entityMount or dismountB
Idempotent

Make one entity ride another, or dismount it.

Inputs: passenger_uuid (required), vehicle_uuid. Returns: object

run_commandRun a console commandA
Destructive

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 advancementB
DestructiveIdempotent

Grant or revoke an advancement for an online player.

Inputs: granted (required), username (required), advancement (required). Returns: object

set_blockSet blockA
DestructiveIdempotent

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 chunkA
Idempotent

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 modeA
Idempotent

Set the game mode that players get when they first join.

Inputs: mode (required). Returns: object

set_difficultySet difficultyA
Idempotent

Change the difficulty of the main world. 'peaceful' removes hostile mobs.

Inputs: level (required). Returns: object

set_entity_aiEnable or disable entity AIB
Idempotent

Turn a mob's AI on or off (living entities only).

Inputs: uuid (required), enabled (required). Returns: object

set_entity_attributeSet entity attributeB
Idempotent

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 equipmentA
DestructiveIdempotent

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 rotationA
Idempotent

Turn an entity to face a direction without moving it.

Inputs: yaw (required), uuid (required), pitch (required). Returns: object

set_entity_targetSet mob targetA
Idempotent

Make a mob attack a specific living entity, or clear its target.

Inputs: uuid (required), target_uuid. Returns: object

set_entity_velocitySet entity velocityA
Idempotent

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 modeA
Idempotent

Change an online player's game mode (survival, creative, adventure or spectator).

Inputs: mode (required), username (required). Returns: object

set_gameruleSet game ruleA
Idempotent

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 slotB
DestructiveIdempotent

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 objectiveA
Idempotent

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 scoreA
DestructiveIdempotent

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 pointA
Idempotent

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 optionB
Idempotent

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 professionA
DestructiveIdempotent

Change a villager's profession. This resets the villager's current trades.

Inputs: uuid (required), profession (required). Returns: object

set_villager_tradesSet villager tradesA
DestructiveIdempotent

Replace all of a villager's trades with custom ones.

Inputs: uuid (required), trades (required). Returns: object

set_weatherSet weatherA
Idempotent

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 spawnB
Idempotent

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 soundsA
Idempotent

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 entityC
Idempotent

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 playerA
Idempotent

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 barA
Idempotent

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 tagsA
Idempotent

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 membersA
Idempotent

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

    B3.3/5.0

    Scored across 86 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    Related MCP Servers