Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
MCPYLIB_HOSTNoHost of the Minecraft server that runs the MCPyLib plugin.localhost
MCPYLIB_PORTNoPlugin port (`server.port` in `plugins/MCPyLib/config.yml`).65535
MCPYLIB_TOKENYesToken printed by `/mcpylib token`. Required to authenticate with the MCPyLib plugin.
MCPYLIB_TIMEOUTNoSeconds to wait for each reply from the plugin.30
MCPYLIB_HTTP_HOSTNoAddress the HTTP transport binds to.127.0.0.1
MCPYLIB_HTTP_PORTNoPort of the HTTP transport. The endpoint is `/mcp`.8000
MCPYLIB_LOG_LEVELNoLog level: `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. Logs go to stderr.INFO
MCPYLIB_READ_ONLYNoRegister only tools that do not change the world.false
MCPYLIB_TRANSPORTNoTransport to use: `stdio`, or `http` for streamable HTTP.stdio
MCPYLIB_MAX_BLOCKSNoThe most blocks one tool call may read or change.100000
MCPYLIB_DENIED_TOOLSNoNever register these tools. Same syntax as the allowlist; the denylist wins over the allowlist. Defaults to none.
MCPYLIB_ALLOWED_TOOLSNoRegister only these tools. Entries are names, globs (`get_*`) or groups (`group:blocks`). Defaults to all tools.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

Controls a live Minecraft Java server (Paper/Spigot with the MCPyLib plugin). Conventions: +X is east, +Z is south, +Y is up (overworld build range Y -64 to 319). Block, world and particle tools act on the server's main world; player and entity tools act wherever that player or entity is. Ids are Minecraft names such as 'minecraft:stone' (the namespace is optional). Work efficiently: find positions with get_players/get_player_position, find the ground with get_height_map, build solid parts with fill_region and detailed parts with build_from_layers, and check the result with get_blocks. Limits: each call may read or change at most 100,000 blocks (MCPYLIB_MAX_BLOCKS); split bigger jobs into several calls. Changes are immediate and cannot be undone: inspect with get_blocks before overwriting player builds. run_command runs any console command; prefer the dedicated tools.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}

Tools

Functions exposed to the LLM to take actions

NameDescription
get_playersA

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

run_commandA

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.

get_blockA

Return the block id at one position, e.g. 'minecraft:stone' (block states are not included).

get_blocksA

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.

get_height_mapA

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.

set_blockA

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.

fill_regionA

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.

clone_regionA

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.

edit_blocksA

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.

build_from_layersA

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.

get_player_positionA

Block position of an online player's feet (rounded down); the block they stand on is at y - 1.

teleport_playerA

Teleport an online player within their current world, optionally setting where they face.

set_gamemodeA

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

give_itemA

Add items to an online player's inventory. Items that do not fit are lost.

get_inventoryA

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.

set_inventory_slotB

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

clear_inventoryA

Remove items from an online player's inventory (all items, or only one item type).

enchant_held_itemA

Add an enchantment to the item in an online player's main hand (fails if the hand is empty).

apply_effectB

Give an online player a status effect such as speed, night_vision or regeneration.

clear_effectsA

Remove one or all status effects from an online player.

get_experienceB

An online player's experience: level, total points and progress (0-1) toward the next level.

update_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.

set_spawnpointA

Set where an online player respawns: the given position, or where they stand now.

get_advancementB

Whether an online player has completed an advancement.

set_advancementB

Grant or revoke an advancement for an online player.

spread_playersA

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

get_timeA

Current time of day in the main world: ticks (0-23999), phase (day/sunset/night/sunrise) and clock.

set_timeA

Set or advance the time of day in the main world.

set_weatherA

Change the weather in the main world to clear, rain or thunder, optionally for a set duration.

set_difficultyA

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

get_gameruleB

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

set_gameruleA

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).

set_world_spawnB

Set the main world's spawn point (where new players appear and compasses point).

set_default_gamemodeA

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

get_world_borderB

The main world's border: size (diameter), centre, damage and warning settings.

set_world_borderA

Change any combination of the main world's border settings in one call; omitted settings are left alone. Returns the resulting border.

get_chunk_force_loadedB

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

set_chunk_force_loadedA

Keep (or stop keeping) the chunk containing block (x, z) of the main world loaded, so redstone and farms there run without players nearby.

fill_biomeA

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.

locate_structureA

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.

place_featureA

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.

place_structureA

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.

place_jigsawB

Generate a jigsaw structure from a template pool. Without coordinates it is placed at world spawn. Only dispatch is reported.

place_templateA

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.

spawn_lootA

Roll a loot table once and drop the resulting items at a position in the main world.

summon_entityA

Spawn an entity in the main world and return its UUID (used by every other entity tool).

kill_entitiesA

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.

remove_entityA

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

get_entityB

Details of one entity: type, custom name, world, position, rotation, velocity, health and AI state.

teleport_entityC

Move an entity to an exact position, optionally setting where it faces.

set_entity_velocityA

Push an entity: set its velocity vector (e.g. vy=1 for a jump of about 7 blocks).

set_entity_rotationA

Turn an entity to face a direction without moving it.

set_entity_aiB

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

set_entity_targetA

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

get_entity_equipmentB

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

set_entity_equipmentA

Equip a living entity (mob or armor stand); slots you omit are left unchanged, and the replaced items are lost.

damage_entityA

Hurt a living entity. Enough damage kills it.

ride_entityB

Make one entity ride another, or dismount it.

get_entity_attributeB

Base and effective value of a living entity's attribute (e.g. max_health, movement_speed).

set_entity_attributeB

Set the base value of a living entity's attribute, e.g. max_health 40 or scale 2.

get_entity_tagsB

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

update_entity_tagsA

Add and/or remove scoreboard tags on an entity and return its resulting tags.

get_villagerC

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

set_villager_professionA

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

set_villager_tradesA

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

broadcast_messageA

Send a chat message to every player; it appears as '[Server] '.

send_messageA

Send a private chat message to one online player.

send_rich_messageA

Send a formatted (coloured, clickable, hoverable) chat message using vanilla /tellraw.

show_titleB

Show a big title and/or subtitle in the middle of an online player's screen.

play_soundA

Play a sound to one online player, at a position or (by default) at the player.

stop_soundA

Stop sounds playing for an online player: one sound, or everything.

spawn_particlesB

Show particles at a position in the main world (visible to nearby players).

create_objectiveA

Create a scoreboard objective (fails if it already exists).

remove_objectiveA

Delete a scoreboard objective and all of its scores.

set_objective_displayA

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

set_scoreA

Set a score holder's score on an objective, replacing the previous value.

get_scoreB

A score holder's score on an objective (0 if they have none).

list_teamsA

All scoreboard teams with their display names and members.

create_teamA

Create a scoreboard team (fails if it already exists).

remove_teamA

Delete a scoreboard team; its members become teamless.

update_team_membersA

Add and/or remove team members (a player can only be in one team; joining moves them).

set_team_optionB

Change a team setting such as its colour or friendly fire.

list_bossbarsB

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

create_bossbarA

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.

update_bossbarA

Change a boss bar's look or progress and who sees it; omitted settings are left alone.

remove_bossbarB

Delete a boss bar and hide it from everyone.

Prompts

Interactive templates invoked by user choice

NameDescription
build_structurePlan and build a structure in the world: survey the site, prepare it, build, and verify.
survey_areaInspect an area without changing it: terrain, materials, water, builds and good sites.

Resources

Contextual data attached and managed by the client

NameDescription
server_statusOnline players, time of day, world border, and this MCP server's limits. Never fails: if the plugin is unreachable it reports connected=false with the reason.
building_guideCoordinates, block states, the layers format and a building workflow for these tools.

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.