Getting started

Install the plugin, copy its token and place your first block from Python.

Requirements

ComponentRequirement
Python3.11 or newer
Minecraft serverPaper or Spigot 26.1 or newer. Built against 26.3, tested on Paper 26.3 and Spigot 26.3
Java25 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.jar

Run /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 token

Run it from the console or in game as an operator. Treat the token like a password: whoever has it controls your server.

CommandWhat it does
/mcpylibShows the plugin version and usage
/mcpylib tokenShows the current token
/mcpylib token regenerateCreates a new token; the old one stops working
/mcpylib statusShows the server status, port and whether token authentication is on
/mcpylib reloadReloads 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.

plugins/MCPyLib/config.yml
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: true

Install the Python client

pip install mcpylib

Or with uv:

uv pip install mcpylib

Place your first block

Read the token from an environment variable instead of hardcoding it:

first_block.py
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.py

The 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 here

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

xyz
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 values
blocks[x][y][z]: the outer list is x (east), then y (up), then z (south). None leaves a position unchanged.
house.py
house = [[[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:

ExceptionRaised when
ConnectionErrorThe 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
AuthenticationErrorThe server rejects the token
CommandErrorA 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

ProblemFix
Connection refusedCheck that the plugin loaded with /plugins and that your script uses the port from config.yml (65535 by default).
Authentication failedCopy the token again with /mcpylib token, without spaces or line breaks. Regenerate it if in doubt.
Player not foundThe player must be online. Names are case-sensitive.
The plugin doesn’t loadRead logs/latest.log, and check that the server runs Java 25 and Paper or Spigot 26.1 or newer.
Port already in useChange server.port in config.yml, restart, and use the same port in your script.

Next steps