Getting started
Install the plugin, copy its token and place your first block from Python.
Requirements
| Component | Requirement |
|---|---|
| Python | 3.11 or newer |
| Minecraft server | Paper or Spigot 26.1 or newer. Built against 26.3, tested on Paper 26.3 and Spigot 26.3 |
| Java | 25 or newer |
Install the server plugin
Download MCPyLib-Plugin-1.2.1.jar from GitHub Releases, put it in your server’s plugins folder and restart the server.
To build it yourself you need Maven and JDK 25:
git clone https://github.com/treeleaves30760/MCPyLib.git
cd MCPyLib/ServerPlugin
mvn clean package
# -> target/MCPyLib-Plugin-1.2.1.jarRun /plugins to check. MCPyLib should be green.
Get your token
On first start the plugin generates a random token and saves it in plugins/MCPyLib/config.yml. Show it with:
/mcpylib tokenRun it from the console or in game as an operator. Treat the token like a password: whoever has it controls your server.
| Command | What it does |
|---|---|
/mcpylib | Shows the plugin version and usage |
/mcpylib token | Shows the current token |
/mcpylib token regenerate | Creates a new token; the old one stops working |
/mcpylib status | Shows the server status, port and whether token authentication is on |
/mcpylib reload | Reloads config.yml |
All of them need mcpylib.admin, which operators have by default. Aliases: /mcpy, /mcp.
Configure the connection
The defaults work for scripts on the same machine. To change them, edit plugins/MCPyLib/config.yml and restart.
server:
port: 65535 # TCP port the plugin listens on
host: '0.0.0.0' # bind address; '127.0.0.1' allows local scripts only
max-connections: 10 # concurrent connections; extras get "Server busy"
idle-timeout-seconds: 300 # close idle connections; 0 = never
security:
token: '' # generated on first start
require-token: true # keep this on
logging:
log-connections: true
log-commands: trueInstall the Python client
pip install mcpylibOr with uv:
uv pip install mcpylibPlace your first block
Read the token from an environment variable instead of hardcoding it:
import os
from mcpylib import MCPyLib
mc = MCPyLib(
ip="127.0.0.1",
port=65535,
token=os.environ["MCPYLIB_TOKEN"], # from /mcpylib token
)
mc.setblock(0, 64, 0, "diamond_block")
print(mc.getblock(0, 64, 0)) # minecraft:diamond_block
count = mc.fill(2, 64, 0, 6, 68, 4, "glass") # returns the number of blocks affected
print(count)Run it with MCPYLIB_TOKEN set:
# macOS and Linux
MCPYLIB_TOKEN=your-token python first_block.py
# Windows PowerShell
$env:MCPYLIB_TOKEN="your-token"; python first_block.pyThe client keeps one connection open and reconnects if it drops. Call mc.close() when you’re done, or use a with block:
with MCPyLib(token=os.environ["MCPYLIB_TOKEN"]) as mc:
mc.say("Hello from Python")
# the connection is closed hereBuild in bulk with edit()
setblock() sends one request per block. edit() sends a whole 3D list in one, so use it for anything bigger than a few blocks.
The list is indexed blocks[x][y][z], starting at the coordinates you pass. Each entry is a block name, None to leave that position unchanged, or a dict with block_state and nbt.
blocks = [
[["stone", "stone"], ["glass", None]], # x = 0
[["stone", "stone"], ["glass", "glass"]], # x = 1
[["stone", "oak_planks"], [None, "glass"]], # x = 2
] # each x holds y layers; each y layer holds z valueshouse = [[[None] * 10 for _ in range(5)] for _ in range(10)] # 10 × 5 × 10, all None
for x in range(10):
for z in range(10):
house[x][0][z] = "stone" # floor
house[x][4][z] = "oak_planks" # roof
for y in range(1, 4):
for i in range(10):
house[i][y][0] = house[i][y][9] = "cobblestone" # north and south walls
house[0][y][i] = house[9][y][i] = "cobblestone" # west and east walls
house[2][1][2] = {
"block": "minecraft:chest",
"block_state": {"facing": "north"},
"nbt": {"CustomName": '{"text":"Storage"}'},
}
placed = mc.edit(100, 64, 200, house)getblocks() returns a region in the same [x][y][z] shape, so you can read an area, change it and write it back:
area = mc.getblocks(100, 64, 200, 109, 68, 209)
for column in area: # x
for row in column: # y
for z, block in enumerate(row):
if block == "minecraft:stone":
row[z] = "minecraft:deepslate"
mc.edit(100, 64, 200, area)Handle errors
Every method raises a subclass of MCPyLibError:
| Exception | Raised when |
|---|---|
ConnectionError | The server can’t be reached, the connection drops, or a command times out. After a timeout the command may still have run on the server |
AuthenticationError | The server rejects the token |
CommandError | A command fails, for example an unknown block or an offline player |
from mcpylib import MCPyLib, AuthenticationError, CommandError, ConnectionError
try:
mc.teleport("Steve", 0, 100, 0)
except CommandError as e:
print("Command failed:", e)
except AuthenticationError:
print("Check the token with /mcpylib token")
except ConnectionError:
print("Is the server running with the plugin loaded?")Troubleshooting
| Problem | Fix |
|---|---|
| Connection refused | Check that the plugin loaded with /plugins and that your script uses the port from config.yml (65535 by default). |
| Authentication failed | Copy the token again with /mcpylib token, without spaces or line breaks. Regenerate it if in doubt. |
| Player not found | The player must be online. Names are case-sensitive. |
| The plugin doesn’t load | Read logs/latest.log, and check that the server runs Java 25 and Paper or Spigot 26.1 or newer. |
| Port already in use | Change server.port in config.yml, restart, and use the same port in your script. |
Next steps
- Browse every method in the API reference.
- Connect an AI assistant with the MCP server and Agent Skills.
- More examples on GitHub: a log cabin, a maze generator, a sand mini-game, entity control and the
fill()vsedit()benchmark.