mcpylib-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCPYLIB_HOST | No | Host of the Minecraft server that runs the MCPyLib plugin. | localhost |
| MCPYLIB_PORT | No | Plugin port (`server.port` in `plugins/MCPyLib/config.yml`). | 65535 |
| MCPYLIB_TOKEN | Yes | Token printed by `/mcpylib token`. Required to authenticate with the MCPyLib plugin. | |
| MCPYLIB_TIMEOUT | No | Seconds to wait for each reply from the plugin. | 30 |
| MCPYLIB_HTTP_HOST | No | Address the HTTP transport binds to. | 127.0.0.1 |
| MCPYLIB_HTTP_PORT | No | Port of the HTTP transport. The endpoint is `/mcp`. | 8000 |
| MCPYLIB_LOG_LEVEL | No | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`. Logs go to stderr. | INFO |
| MCPYLIB_READ_ONLY | No | Register only tools that do not change the world. | false |
| MCPYLIB_TRANSPORT | No | Transport to use: `stdio`, or `http` for streamable HTTP. | stdio |
| MCPYLIB_MAX_BLOCKS | No | The most blocks one tool call may read or change. | 100000 |
| MCPYLIB_DENIED_TOOLS | No | Never register these tools. Same syntax as the allowlist; the denylist wins over the allowlist. Defaults to none. | |
| MCPYLIB_ALLOWED_TOOLS | No | Register 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
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| 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 |
| get_height_mapA | Find the ground: for each column of an X/Z area, the Y of the highest block that is not air.
|
| 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
| Name | Description |
|---|---|
| build_structure | Plan and build a structure in the world: survey the site, prepare it, build, and verify. |
| survey_area | Inspect an area without changing it: terrain, materials, water, builds and good sites. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| server_status | Online 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_guide | Coordinates, block states, the layers format and a building workflow for these tools. |
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.