API reference

Generated from client.py in MCPyLib 1.2.1. Each method sends one request and returns the result or raises.

The client

One MCPyLib per server. It connects on the first call, stays connected and reconnects once if the connection drops.

MCPyLib

MCPyLib(
    ip: str = '127.0.0.1',
    port: int = 65535,
    token: str = '',
    timeout: float = 10.0,
)

Main client class for interacting with Minecraft server

Parameters

ipstr= '127.0.0.1'

Server IP address

portint= 65535

Server port

tokenstr= ''

Authentication token

timeoutfloat= 10.0

Socket timeout in seconds

Example

>>> mc = MCPyLib(ip="127.0.0.1", port=65535, token="your_token")
>>> mc.setblock(100, 64, 200, "minecraft:stone")
1
>>> mc.getblock(100, 64, 200)
'minecraft:stone'

client.py line 47

close

mc.close()

Close the persistent connection to the server

Call this when you are done using the client to release resources.

client.py line 126

Context manager

A with block closes the connection when it ends.

from mcpylib import MCPyLib

with MCPyLib(token="YOUR_TOKEN") as mc:
    mc.setblock(0, 64, 0, "stone")
# The connection is closed here.

Exceptions

All errors derive from MCPyLibError. The client raises AuthenticationError when the server’s error message mentions the token, and CommandError for every other failed command.

  • MCPyLibError(Exception)Base exception for MCPyLib errors
  • ConnectionError(MCPyLibError)Raised when connection to server fails
  • AuthenticationError(MCPyLibError)Raised when authentication fails
  • CommandError(MCPyLibError)Raised when a command execution fails

Importing ConnectionError from mcpylib shadows Python’s built-in one in that module.

Blocks

Place, read, copy and bulk-edit blocks. edit() is the fast path for large builds.

setblock

mc.setblock(
    x: int,
    y: int,
    z: int,
    block_name: str,
    block_state: dict = None,
    nbt: dict = None,
) -> int

Set a block at the specified coordinates

Parameters

xintrequired

X coordinate

yintrequired

Y coordinate

zintrequired

Z coordinate

block_namestrrequired

Block type (e.g., "minecraft:stone")

block_statedict= None

Optional block state properties (e.g., {"facing": "north", "half": "bottom"}). Any vanilla property of the block is accepted.

nbtdict= None

Optional block entity data. Only two keys are applied: "CustomName" (plain text, for containers such as chests) and "Text1"-"Text4" (sign lines). Other keys are ignored.

Returns

int 1 if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If command execution fails

Example

>>> mc.setblock(100, 64, 200, "minecraft:stone")
1
>>> mc.setblock(100, 64, 200, "minecraft:oak_stairs", block_state={"facing": "north", "half": "bottom"})
1
>>> mc.setblock(100, 64, 200, "minecraft:chest", nbt={"CustomName": "My Chest"})
1

Sent as setblockclient.py line 228

getblock

mc.getblock(x: int, y: int, z: int) -> str

Get the block type at the specified coordinates

Parameters

xintrequired

X coordinate

yintrequired

Y coordinate

zintrequired

Z coordinate

Returns

str Block type (e.g., "minecraft:stone")

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If command execution fails

Example

>>> mc.getblock(100, 64, 200)
'minecraft:stone'

Sent as getblockclient.py line 281

getblocks

mc.getblocks(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
) -> List[List[List[str]]]

Get all blocks in a rectangular region as a 3D array

Returns a 3D array in the same [x][y][z] format used by edit(), so you can read a region, modify it, and write it back with edit().

Parameters

x1intrequired

Starting X coordinate

y1intrequired

Starting Y coordinate

z1intrequired

Starting Z coordinate

x2intrequired

Ending X coordinate

y2intrequired

Ending Y coordinate

z2intrequired

Ending Z coordinate

Returns

List[List[List[str]]] 3D list of block types [x][y][z] (e.g., "minecraft:stone")

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If command execution fails

Examples

>>> blocks = mc.getblocks(100, 64, 200, 102, 65, 202)
>>> print(blocks[0][0][0])
'minecraft:stone'
>>> # Read, modify, and write back
>>> blocks = mc.getblocks(100, 64, 200, 110, 68, 210)
>>> for x in range(len(blocks)):
...     for y in range(len(blocks[0])):
...         for z in range(len(blocks[0][0])):
...             if blocks[x][y][z] == "minecraft:stone":
...                 blocks[x][y][z] = "minecraft:diamond_block"
>>> mc.edit(min(100, 110), min(64, 68), min(200, 210), blocks)

Sent as getblocksclient.py line 308

fill

mc.fill(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
    block_name: str,
) -> int

Fill a region with the specified block

Parameters

x1intrequired

Starting X coordinate

y1intrequired

Starting Y coordinate

z1intrequired

Starting Z coordinate

x2intrequired

Ending X coordinate

y2intrequired

Ending Y coordinate

z2intrequired

Ending Z coordinate

block_namestrrequired

Block type (e.g., "minecraft:glass")

Returns

int Number of blocks affected

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If command execution fails

Example

>>> mc.fill(100, 64, 200, 110, 74, 210, "minecraft:glass")  # 11x11x11, corners inclusive
1331

Sent as fillclient.py line 358

clone

mc.clone(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
    dest_x: int,
    dest_y: int,
    dest_z: int,
) -> int

Clone a region of blocks to a new location

Parameters

x1intrequired

Source region start X coordinate

y1intrequired

Source region start Y coordinate

z1intrequired

Source region start Z coordinate

x2intrequired

Source region end X coordinate

y2intrequired

Source region end Y coordinate

z2intrequired

Source region end Z coordinate

dest_xintrequired

Destination X coordinate

dest_yintrequired

Destination Y coordinate

dest_zintrequired

Destination Z coordinate

Returns

int Number of blocks cloned

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If region too large (max 32768 blocks)

Example

>>> mc.clone(0, 64, 0, 10, 74, 10, 20, 64, 0)  # 11x11x11, corners inclusive
1331

Sent as cloneclient.py line 1106

edit

mc.edit(
    x: int,
    y: int,
    z: int,
    blocks: List[List[List]],
) -> int

Bulk edit a 3D region of blocks with high performance (like WorldEdit)

This method allows you to quickly place large numbers of different blocks in a single operation, making it ideal for constructing large buildings and structures. It's much faster than using setblock repeatedly.

Parameters

xintrequired

Starting X coordinate

yintrequired

Starting Y coordinate

zintrequired

Starting Z coordinate

blocksList[List[List]]required

3D array of blocks [x][y][z], where each element can be:

  • str: Block name (e.g., "minecraft:stone")
  • None: Skip this position (leave unchanged)
  • dict: Complex block with state and NBT:
    {
        "block": "minecraft:chest",
        "block_state": {"facing": "north"},  # Optional
        "nbt": {"CustomName": "Storage"}  # Optional, same keys as setblock()
    }
    Doors, beds and tall plants can be given as one entry (the lower half or the bed's foot); the other half is added automatically unless the array sets that position itself.

Returns

int Number of blocks placed (None entries and added halves are not counted)

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid block data or coordinates

Examples

>>> # Simple 2x2x2 cube of stone and glass
>>> blocks = [
...     [["stone", "glass"], ["stone", "glass"]],
...     [["stone", "glass"], ["stone", "glass"]]
... ]
>>> mc.edit(100, 64, 200, blocks)
8
>>> # Mixed mode with simple and complex blocks
>>> blocks = [
...     [[None, "stone"], ["glass", None]],
...     [[{
...         "block": "minecraft:chest",
...         "block_state": {"facing": "north"},
...         "nbt": {"CustomName": "Loot"}
...     }, "stone"], ["diamond_block", "gold_block"]]
... ]
>>> mc.edit(100, 64, 200, blocks)
6
>>> # Build a 10x5x10 house with different materials
>>> import numpy as np
>>> blocks = np.full((10, 5, 10), None, dtype=object)
>>> # Floor
>>> blocks[:, 0, :] = "stone"
>>> # Walls
>>> blocks[0, :, :] = "cobblestone"
>>> blocks[9, :, :] = "cobblestone"
>>> blocks[:, :, 0] = "cobblestone"
>>> blocks[:, :, 9] = "cobblestone"
>>> # Roof
>>> blocks[:, 4, :] = "oak_planks"
>>> mc.edit(100, 64, 200, blocks.tolist())
308

Sent as bulkEditclient.py line 1147

Players

Find and teleport players, change game modes, give items, set spawn points and advancements.

getPos

mc.getPos(username: str) -> List[int]

Get the position of a player

Parameters

usernamestrrequired

Player username

Returns

List[int] List of [x, y, z] coordinates

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If command execution fails (e.g., player not found)

Example

>>> mc.getPos("Steve")
[100, 64, 200]

Sent as getPosclient.py line 398

teleport

mc.teleport(
    username: str,
    x: float,
    y: float,
    z: float,
    yaw: float = None,
    pitch: float = None,
) -> bool

Teleport player to coordinates

Parameters

usernamestrrequired

Player username

xfloatrequired

X coordinate

yfloatrequired

Y coordinate

zfloatrequired

Z coordinate

yawfloat= None

Optional rotation yaw angle

pitchfloat= None

Optional rotation pitch angle

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or teleport fails

Example

>>> mc.teleport("Steve", 100, 64, 200)
True
>>> mc.teleport("Steve", 100, 64, 200, yaw=90.0, pitch=0.0)
True

Sent as teleportclient.py line 421

gamemode

mc.gamemode(username: str, mode: str) -> bool

Change player gamemode

Parameters

usernamestrrequired

Player username

modestrrequired

Gamemode (survival, creative, adventure, spectator)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid gamemode

Example

>>> mc.gamemode("Steve", "creative")
True
>>> mc.gamemode("Steve", "survival")
True

Sent as gamemodeclient.py line 460

give

mc.give(username: str, item: str, amount: int = 1) -> bool

Give items to player

Parameters

usernamestrrequired

Player username

itemstrrequired

Item type (e.g., "minecraft:diamond")

amountint= 1

Quantity (1-64, default: 1)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found, invalid item, or amount out of range

Example

>>> mc.give("Steve", "minecraft:diamond", 10)
True
>>> mc.give("Steve", "diamond_sword")
True

Sent as giveclient.py line 551

spawnpoint

mc.spawnpoint(
    username: str,
    x: float = None,
    y: float = None,
    z: float = None,
) -> bool

Set a player's spawn point

Parameters

usernamestrrequired

Player username

xfloat= None

X coordinate (default: player's current position)

yfloat= None

Y coordinate (default: player's current position)

zfloat= None

Z coordinate (default: player's current position)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found

Example

>>> mc.spawnpoint("Steve", 100, 64, 200)
True
>>> mc.spawnpoint("Steve")  # Use current position
True

Sent as spawnpointclient.py line 1698

advancement

mc.advancement(
    username: str,
    action: str,
    advancement_key: str,
) -> bool

Grant, revoke, or query player advancements

Parameters

usernamestrrequired

Player username

actionstrrequired

Action ("grant", "revoke", or "query")

advancement_keystrrequired

Advancement key (e.g., "story/mine_stone", "minecraft:story/iron_tools")

Returns

bool True if successful (for grant/revoke), or bool for query (whether completed)

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid advancement

Example

>>> mc.advancement("Steve", "grant", "story/mine_stone")
True
>>> mc.advancement("Steve", "query", "story/mine_stone")
True

Sent as advancementclient.py line 2265

Effects & experience

Status effects, experience points and levels, and enchantments.

effect

mc.effect(
    username: str,
    effect_type: str,
    duration: int = 30,
    amplifier: int = 0,
    hide_particles: bool = False,
) -> bool

Apply a potion effect to a player

Parameters

usernamestrrequired

Player username

effect_typestrrequired

Effect type (e.g., "speed", "strength", "minecraft:invisibility")

durationint= 30

Duration in seconds (default: 30)

amplifierint= 0

Effect amplifier/level (0 = level I, 1 = level II, etc.)

hide_particlesbool= False

Whether to hide effect particles

Returns

bool True if the effect was applied successfully

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid effect type

Example

>>> mc.effect("Steve", "speed", duration=60, amplifier=1)
True
>>> mc.effect("Steve", "minecraft:invisibility", hide_particles=True)
True

Sent as effectclient.py line 1311

clearEffect

mc.clearEffect(
    username: str,
    effect_type: str = None,
) -> bool

Remove potion effects from a player

Parameters

usernamestrrequired

Player username

effect_typestr= None

Specific effect to remove, or None to remove all effects

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid effect type

Example

>>> mc.clearEffect("Steve", "speed")
True
>>> mc.clearEffect("Steve")  # Remove all effects
True

Sent as clearEffectclient.py line 1345

experience

mc.experience(
    username: str,
    action: str,
    amount: int = 0,
    target: str = 'points',
) -> dict

Manage player experience points and levels

Parameters

usernamestrrequired

Player username

actionstrrequired

Action to perform ("add", "set", or "query")

amountint= 0

Amount of XP points or levels. Note that "set" with target="points" only sets the progress bar within the current level (amount / points needed for the next level, clamped to 0-1).

targetstr= 'points'

Target type ("points" or "levels")

Returns

dict Dictionary with keys: level, points (total XP, from level and progress), progress

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid action

Example

>>> mc.experience("Steve", "add", 100)
{'level': 7, 'points': 100, 'progress': 0.43}
>>> mc.experience("Steve", "set", 10, target="levels")
{'level': 10, 'points': 172, 'progress': 0.43}
>>> mc.experience("Steve", "query")
{'level': 10, 'points': 172, 'progress': 0.43}

Sent as experienceclient.py line 1398

enchant

mc.enchant(
    username: str,
    enchantment: str,
    level: int = 1,
) -> bool

Enchant the item in a player's main hand

Parameters

usernamestrrequired

Player username

enchantmentstrrequired

Enchantment name (e.g., "sharpness", "minecraft:unbreaking")

levelint= 1

Enchantment level (default: 1)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found, not holding item, or invalid enchantment

Example

>>> mc.enchant("Steve", "sharpness", 5)
True

Sent as enchantclient.py line 2155

Inventory

Read and change inventory slots.

clear

mc.clear(
    username: str,
    item: str = None,
    max_count: int = -1,
) -> int

Clear items from a player's inventory

Parameters

usernamestrrequired

Player username

itemstr= None

Item type to clear (e.g., "diamond"), or None to clear all

max_countint= -1

Maximum number of items to remove (-1 for all)

Returns

int Number of items removed

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid item type

Example

>>> mc.clear("Steve")  # Clear entire inventory
64
>>> mc.clear("Steve", "diamond", 10)  # Remove up to 10 diamonds
10

Sent as clearclient.py line 1371

getItem

mc.getItem(username: str, slot: int) -> dict

Get item information from a player's inventory slot

Parameters

usernamestrrequired

Player username

slotintrequired

Inventory slot number (0-35 for main inventory)

Returns

dict Dictionary with item, amount, and (if any) enchantments. For an empty slot it is {'amount': 0} (the "item" key is left out).

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid slot

Example

>>> mc.getItem("Steve", 0)
{'item': 'minecraft:diamond_sword', 'amount': 1, 'enchantments': {'sharpness': 5}}

Sent as getItemclient.py line 2182

setItem

mc.setItem(
    username: str,
    slot: int,
    item: str,
    amount: int = 1,
) -> bool

Set an item in a player's inventory slot

Parameters

usernamestrrequired

Player username

slotintrequired

Inventory slot number (0-35 for main inventory)

itemstrrequired

Item type (e.g., "diamond_sword", "minecraft:golden_apple")

amountint= 1

Item count (default: 1)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found, invalid slot, or invalid item

Example

>>> mc.setItem("Steve", 0, "diamond_sword")
True

Sent as setItemclient.py line 2205

World settings

Time, weather, difficulty, game rules, spawn, world border and chunk loading.

time

mc.time(action: str, value: int = None) -> int

Control world time

Parameters

actionstrrequired

Action to perform (set, add, query)

valueint= None

Time value (0-24000) for set/add actions

Returns

int Current world time

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid action or value out of range

Example

>>> mc.time("set", 1000)
1000
>>> mc.time("add", 6000)
7000
>>> mc.time("query")
7000

Sent as timeclient.py line 487

weather

mc.weather(condition: str, duration: int = None) -> bool

Control world weather

Parameters

conditionstrrequired

Weather condition (clear, rain, thunder)

durationint= None

Optional duration in seconds

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid condition

Example

>>> mc.weather("clear")
True
>>> mc.weather("rain", duration=600)
True
>>> mc.weather("thunder", duration=300)
True

Sent as weatherclient.py line 519

difficulty

mc.difficulty(level: str) -> bool

Set the world difficulty

Parameters

levelstrrequired

Difficulty level ("peaceful", "easy", "normal", "hard")

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid difficulty level

Example

>>> mc.difficulty("hard")
True

Sent as difficultyclient.py line 1435

gamerule

mc.gamerule(rule: str, value: str = None) -> str

Get or set a game rule

Parameters

rulestrrequired

Game rule name (e.g., "keep_inventory", "mob_griefing"; legacy camelCase names like "keepInventory" are also accepted)

valuestr= None

Value to set, or None to query current value

Returns

str Current value of the game rule as string

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid game rule

Example

>>> mc.gamerule("doDaylightCycle", "false")
'false'
>>> mc.gamerule("keep_inventory")
'false'

Sent as gameruleclient.py line 1456

defaultgamemode

mc.defaultgamemode(mode: str) -> bool

Set the default game mode for new players

Parameters

modestrrequired

Game mode (survival, creative, adventure, spectator)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid game mode

Example

>>> mc.defaultgamemode("creative")
True

Sent as defaultgamemodeclient.py line 2571

setworldspawn

mc.setworldspawn(x: int, y: int, z: int) -> bool

Set the world spawn location

Parameters

xintrequired

X coordinate

yintrequired

Y coordinate

zintrequired

Z coordinate

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If setting spawn fails

Example

>>> mc.setworldspawn(0, 64, 0)
True

Sent as setworldspawnclient.py line 1729

worldborder

mc.worldborder(
    action: str,
    value: float = None,
    time: int = None,
    x: float = None,
    z: float = None,
) -> dict

Manage the world border

Parameters

actionstrrequired

Action ("get", "set", "center", "add", "damage", "warning")

valuefloat= None

Size value for set/add, damage amount for damage, warning distance for warning

timeint= None

Transition time in seconds for set/add, warning time for warning

xfloat= None

X coordinate for center action

zfloat= None

Z coordinate for center action

Returns

dict Dictionary with border information

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid action or parameters

Example

>>> mc.worldborder("get")
{'size': 59999968.0, 'center_x': 0.0, 'center_z': 0.0, 'damage_amount': 0.2, 'damage_buffer': 5.0, 'warning_distance': 5, 'warning_time': 15}
>>> mc.worldborder("set", value=1000, time=10)
{'size': 1000.0}
>>> mc.worldborder("center", x=100, z=200)
{'center_x': 100.0, 'center_z': 200.0}

Sent as worldborderclient.py line 1752

forceload

mc.forceload(action: str, x: int, z: int) -> bool

Force-load or unload chunks

Parameters

actionstrrequired

Action ("add", "remove", "query")

xintrequired

Block X coordinate (will be converted to chunk coordinate)

zintrequired

Block Z coordinate (will be converted to chunk coordinate)

Returns

bool True/False for add/remove/query operations

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid action

Example

>>> mc.forceload("add", 100, 200)
True
>>> mc.forceload("query", 100, 200)
True
>>> mc.forceload("remove", 100, 200)
True

Sent as forceloadclient.py line 1790

Chat, sound & particles

Messages, titles, sounds and particle effects.

say

mc.say(message: str) -> bool

Broadcast a message to all players

Parameters

messagestrrequired

Message to broadcast

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If broadcast fails

Example

>>> mc.say("Hello everyone!")
True

Sent as sayclient.py line 1483

tell

mc.tell(username: str, message: str) -> bool

Send a private message to a player

Parameters

usernamestrrequired

Player username

messagestrrequired

Message to send

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found

Example

>>> mc.tell("Steve", "Hello Steve!")
True

Sent as tellclient.py line 1504

tellraw

mc.tellraw(username: str, json_text: str) -> bool

Send a raw JSON text message to a player

The request is run as the vanilla ``tellraw`` command, so ``username`` may also be a target selector such as "@a".

Parameters

usernamestrrequired

Player username (or a target selector)

json_textstrrequired

JSON text component as a string (not a dict or list)

Returns

bool True once the command was dispatched (an unknown player is only reported in the server log)

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid JSON

Example

>>> mc.tellraw("Steve", '{"text":"Hello","color":"gold","bold":true}')
True

Sent as tellrawclient.py line 1526

title

mc.title(
    username: str,
    title: str = '',
    subtitle: str = '',
    fade_in: int = 10,
    stay: int = 70,
    fade_out: int = 20,
) -> bool

Display a title on a player's screen

Parameters

usernamestrrequired

Player username

titlestr= ''

Main title text

subtitlestr= ''

Subtitle text

fade_inint= 10

Fade in time in ticks (default: 10)

stayint= 70

Stay time in ticks (default: 70)

fade_outint= 20

Fade out time in ticks (default: 20)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found

Example

>>> mc.title("Steve", "Welcome!", "Enjoy your stay")
True

Sent as titleclient.py line 1552

playsound

mc.playsound(
    username: str,
    sound: str,
    source: str = 'master',
    x: float = None,
    y: float = None,
    z: float = None,
    volume: float = 1.0,
    pitch: float = 1.0,
) -> bool

Play a sound for a player

Parameters

usernamestrrequired

Player username

soundstrrequired

Sound name (e.g., "entity.experience_orb.pickup")

sourcestr= 'master'

Sound source category (master, music, record, weather, block, hostile, neutral, player, ambient, voice)

xfloat= None

X coordinate (default: player position)

yfloat= None

Y coordinate (default: player position)

zfloat= None

Z coordinate (default: player position)

volumefloat= 1.0

Volume (default: 1.0)

pitchfloat= 1.0

Pitch (default: 1.0)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found or invalid sound

Example

>>> mc.playsound("Steve", "entity.experience_orb.pickup")
True
>>> mc.playsound("Steve", "block.note_block.harp", x=100, y=64, z=200, pitch=1.5)
True

Sent as playsoundclient.py line 1586

stopsound

mc.stopsound(
    username: str,
    sound: str = None,
    source: str = None,
) -> bool

Stop sounds for a player

Parameters

usernamestrrequired

Player username

soundstr= None

Specific sound to stop, or None to stop all sounds

sourcestr= None

Sound category of ``sound`` (only used together with ``sound``; without a sound, all sounds stop)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If player not found

Example

>>> mc.stopsound("Steve")  # Stop all sounds
True
>>> mc.stopsound("Steve", "minecraft:music.creative")
True

Sent as stopsoundclient.py line 1628

particle

mc.particle(
    particle_type: str,
    x: float,
    y: float,
    z: float,
    count: int = 1,
    dx: float = 0,
    dy: float = 0,
    dz: float = 0,
    speed: float = 0,
) -> bool

Spawn particles at a location

Particles that need extra data (such as "dust", "block" or "item") are not supported and raise CommandError.

Parameters

particle_typestrrequired

Particle type (e.g., "flame", "heart", "minecraft:smoke")

xfloatrequired

X coordinate

yfloatrequired

Y coordinate

zfloatrequired

Z coordinate

countint= 1

Number of particles (default: 1)

dxfloat= 0

X spread (default: 0)

dyfloat= 0

Y spread (default: 0)

dzfloat= 0

Z spread (default: 0)

speedfloat= 0

Particle speed (default: 0)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid particle type

Example

>>> mc.particle("flame", 100, 65, 200, count=50, dx=1, dy=1, dz=1, speed=0.1)
True

Sent as particleclient.py line 1658

Entities

Summon entities and control their position, motion, AI, health, riding and attributes.

summon

mc.summon(
    entity_type: str,
    x: float,
    y: float,
    z: float,
) -> str

Summon an entity at coordinates

Parameters

entity_typestrrequired

Entity type (e.g., "minecraft:zombie", "pig")

xfloatrequired

X coordinate

yfloatrequired

Y coordinate

zfloatrequired

Z coordinate

Returns

str Entity UUID as string

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid entity type or coordinates

Example

>>> uuid = mc.summon("minecraft:zombie", 100, 64, 200)
>>> uuid = mc.summon("pig", 150, 70, 250)

Sent as summonclient.py line 580

kill

mc.kill(selector: str) -> int

Remove entities from the world

Only three selector forms are understood (vanilla selectors such as "@e[type=zombie]" or UUIDs are rejected). "all" and entity types act on the first (main) world and remove at most 1000 entities per call.

Parameters

selectorstrrequired

"all" (every non-player entity, including dropped items, armor stands and item frames), an entity type such as "zombie", or "player:username" (sets that player's health to 0)

Returns

int Number of entities killed

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid selector or player not found

Example

>>> mc.kill("all")
42
>>> mc.kill("zombie")
5
>>> mc.kill("player:Steve")
1

Sent as killclient.py line 609

getEntityPos

mc.getEntityPos(entity_uuid: str) -> dict

Get the position of an entity by UUID

Parameters

entity_uuidstrrequired

Entity UUID string

Returns

dict Position dictionary with keys: x, y, z, yaw, pitch

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or invalid UUID

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> pos = mc.getEntityPos(uuid)
>>> print(f"Position: ({pos['x']}, {pos['y']}, {pos['z']})")

Sent as getEntityPosclient.py line 642

getEntityStatus

mc.getEntityStatus(entity_uuid: str) -> dict

Get complete status information of an entity

Parameters

entity_uuidstrrequired

Entity UUID string

Returns

dict Status dictionary containing: - uuid: Entity UUID - type: Entity type (e.g., "minecraft:zombie") - custom_name: Custom name (key omitted when the entity has none) - is_valid: Whether entity is valid - is_dead: Whether entity is dead - position: {x, y, z} coordinates - velocity: {x, y, z} velocity vector - world: World name - health: Current health (LivingEntity only, key omitted otherwise) - max_health: Maximum health (LivingEntity only, key omitted otherwise) - has_ai: Whether AI is enabled (LivingEntity only, key omitted otherwise) The server leaves out keys whose value would be null, so use status.get("custom_name") for the optional ones.

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or invalid UUID

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> status = mc.getEntityStatus(uuid)
>>> print(f"Health: {status['health']}/{status['max_health']}")
>>> print(f"AI enabled: {status['has_ai']}")

Sent as getEntityStatusclient.py line 666

teleportEntity

mc.teleportEntity(
    entity_uuid: str,
    x: float,
    y: float,
    z: float,
    yaw: float = None,
    pitch: float = None,
) -> bool

Teleport an entity to specified coordinates

Parameters

entity_uuidstrrequired

Entity UUID string

xfloatrequired

Target X coordinate

yfloatrequired

Target Y coordinate

zfloatrequired

Target Z coordinate

yawfloat= None

Optional rotation yaw angle

pitchfloat= None

Optional rotation pitch angle

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or teleport fails

Example

>>> uuid = mc.summon("pig", 100, 64, 200)
>>> mc.teleportEntity(uuid, 110, 70, 210)
True
>>> mc.teleportEntity(uuid, 120, 64, 220, yaw=90.0, pitch=0.0)
True

Sent as teleportEntityclient.py line 705

setEntityVelocity

mc.setEntityVelocity(
    entity_uuid: str,
    vx: float,
    vy: float,
    vz: float,
) -> bool

Set the velocity of an entity

Parameters

entity_uuidstrrequired

Entity UUID string

vxfloatrequired

X velocity component (blocks/tick, clamped to ±10)

vyfloatrequired

Y velocity component (blocks/tick, clamped to ±10)

vzfloatrequired

Z velocity component (blocks/tick, clamped to ±10)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found

Example

>>> uuid = mc.summon("pig", 100, 64, 200)
>>> # Make the pig jump
>>> mc.setEntityVelocity(uuid, 0, 1.0, 0)
True
>>> # Push the pig forward
>>> mc.setEntityVelocity(uuid, 0.5, 0.2, 0.5)
True

Sent as setEntityVelocityclient.py line 752

setEntityRotation

mc.setEntityRotation(
    entity_uuid: str,
    yaw: float,
    pitch: float,
) -> bool

Set the rotation (facing direction) of an entity

Parameters

entity_uuidstrrequired

Entity UUID string

yawfloatrequired

Horizontal rotation angle (0=south, 90=west, 180=north, 270=east)

pitchfloatrequired

Vertical rotation angle (-90=up, 0=horizontal, 90=down)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If the entity is not found, or a player's rotation was blocked (for example by another plugin)

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> # Face north
>>> mc.setEntityRotation(uuid, 180.0, 0.0)
True
>>> # Look up
>>> mc.setEntityRotation(uuid, 180.0, -45.0)
True

Sent as setEntityRotationclient.py line 792

setEntityAI

mc.setEntityAI(entity_uuid: str, enabled: bool) -> bool

Enable or disable AI for a living entity

When AI is disabled, the entity will not move, attack, or perform any autonomous behavior (like a statue).

Parameters

entity_uuidstrrequired

Entity UUID string

enabledboolrequired

True to enable AI, False to disable

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or not a LivingEntity

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> # Freeze the zombie (disable AI)
>>> mc.setEntityAI(uuid, False)
True
>>> # Re-enable AI
>>> mc.setEntityAI(uuid, True)
True

Sent as setEntityAIclient.py line 830

setEntityTarget

mc.setEntityTarget(
    entity_uuid: str,
    target_uuid: str = None,
) -> bool

Set or clear the attack target of a mob entity

Parameters

entity_uuidstrrequired

UUID of the mob entity

target_uuidstr= None

UUID of the target entity (must be a LivingEntity), or None to clear the target

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found, not a Mob, or target is invalid

Example

>>> zombie = mc.summon("zombie", 100, 64, 200)
>>> villager = mc.summon("villager", 105, 64, 200)
>>> # Make zombie target the villager
>>> mc.setEntityTarget(zombie, villager)
True
>>> # Clear the target
>>> mc.setEntityTarget(zombie, None)
True

Sent as setEntityTargetclient.py line 863

removeEntity

mc.removeEntity(entity_uuid: str) -> bool

Remove an entity from the world

Parameters

entity_uuidstrrequired

Entity UUID string

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or is a player

Example

>>> uuid = mc.summon("pig", 100, 64, 200)
>>> mc.removeEntity(uuid)
True

Sent as removeEntityclient.py line 900

damage

mc.damage(
    entity_uuid: str,
    amount: float,
    source_uuid: str = None,
) -> bool

Deal damage to an entity

Parameters

entity_uuidstrrequired

Target entity UUID

amountfloatrequired

Damage amount

source_uuidstr= None

Optional UUID of the entity dealing damage

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or not a LivingEntity

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> mc.damage(uuid, 5.0)
True

Sent as damageclient.py line 1817

ride

mc.ride(
    passenger_uuid: str,
    vehicle_uuid: str = None,
) -> bool

Make an entity ride another entity, or dismount

Parameters

passenger_uuidstrrequired

UUID of the passenger entity

vehicle_uuidstr= None

UUID of the vehicle entity, or None to dismount

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found

Example

>>> pig = mc.summon("pig", 100, 64, 200)
>>> zombie = mc.summon("zombie", 100, 64, 200)
>>> mc.ride(zombie, pig)  # Zombie rides the pig
True
>>> mc.ride(zombie)  # Zombie dismounts
True

Sent as rideclient.py line 2507

attribute

mc.attribute(
    entity_uuid: str,
    attribute_name: str,
    action: str = 'get',
    value: float = None,
) -> dict

Get or set entity attributes

Parameters

entity_uuidstrrequired

Entity UUID

attribute_namestrrequired

Attribute name (e.g., "MAX_HEALTH", "MOVEMENT_SPEED", "ATTACK_DAMAGE")

actionstr= 'get'

Action ("get" or "set")

valuefloat= None

Value to set (required for "set" action)

Returns

dict Dictionary with base_value and value

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or invalid attribute

Example

>>> mc.attribute(uuid, "MAX_HEALTH")
{'base_value': 20.0, 'value': 20.0}
>>> mc.attribute(uuid, "MAX_HEALTH", action="set", value=40.0)
{'base_value': 40.0, 'value': 40.0}

Sent as attributeclient.py line 2122

Equipment & tags

Armor and held items, plus scoreboard tags for grouping entities.

getEntityEquipment

mc.getEntityEquipment(entity_uuid: str) -> dict

Get the equipment of a living entity

Parameters

entity_uuidstrrequired

Entity UUID string

Returns

dict Equipment dictionary with these keys (item ids such as "minecraft:diamond_helmet"); empty slots are left out: - helmet - chestplate - leggings - boots - main_hand - off_hand

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or doesn't support equipment

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> equipment = mc.getEntityEquipment(uuid)
>>> print(f"Helmet: {equipment.get('helmet')}")  # None if no helmet

Sent as getEntityEquipmentclient.py line 924

setEntityEquipment

mc.setEntityEquipment(
    entity_uuid: str,
    equipment: dict,
    drop_chances: dict = None,
) -> bool

Set the equipment of a living entity

Parameters

entity_uuidstrrequired

Entity UUID string

equipmentdictrequired

Dictionary of equipment slots to set. Keys can be:

  • helmet: Item name (e.g., "diamond_helmet")
  • chestplate: Item name
  • leggings: Item name
  • boots: Item name
  • main_hand: Item name
  • off_hand: Item name
drop_chancesdict= None

Optional dictionary of drop chances (0.0-1.0) for each slot

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or doesn't support equipment

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> mc.setEntityEquipment(uuid, {
...     "helmet": "diamond_helmet",
...     "chestplate": "diamond_chestplate",
...     "main_hand": "diamond_sword"
... }, drop_chances={"helmet": 0.1, "main_hand": 0.5})
True

Sent as setEntityEquipmentclient.py line 955

addTag

mc.addTag(entity_uuid: str, tag: str) -> bool

Add a scoreboard tag to an entity

Parameters

entity_uuidstrrequired

Entity UUID

tagstrrequired

Tag string

Returns

bool True if the tag was added (False if already had it)

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found

Example

>>> uuid = mc.summon("zombie", 100, 64, 200)
>>> mc.addTag(uuid, "boss")
True

Sent as addTagclient.py line 1962

removeTag

mc.removeTag(entity_uuid: str, tag: str) -> bool

Remove a scoreboard tag from an entity

Parameters

entity_uuidstrrequired

Entity UUID

tagstrrequired

Tag string

Returns

bool True if the tag was removed

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found

Example

>>> mc.removeTag(uuid, "boss")
True

Sent as removeTagclient.py line 1985

getTags

mc.getTags(entity_uuid: str) -> List[str]

Get all scoreboard tags of an entity

Parameters

entity_uuidstrrequired

Entity UUID

Returns

List[str] List of tag strings

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found

Example

>>> mc.getTags(uuid)
['boss', 'enemy']

Sent as getTagsclient.py line 2007

Villagers

Professions, levels and custom trades.

getVillagerData

mc.getVillagerData(villager_uuid: str) -> dict

Get villager profession, level, and trade information

Parameters

villager_uuidstrrequired

Villager entity UUID string

Returns

dict Dictionary containing: - profession: Villager profession name (e.g., "LIBRARIAN") - level: Villager level (1-5) - trades: List of trade dictionaries, each containing: - buy1: {"item": str, "amount": int} - buy2: {"item": str, "amount": int} (only present when the trade has a second ingredient) - sell: {"item": str, "amount": int} - uses: Current number of uses - max_uses: Maximum number of uses

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found or not a villager

Example

>>> uuid = mc.summon("villager", 100, 64, 200)
>>> data = mc.getVillagerData(uuid)
>>> print(f"Profession: {data['profession']}")
>>> print(f"Number of trades: {len(data['trades'])}")

Sent as getVillagerDataclient.py line 999

setVillagerProfession

mc.setVillagerProfession(
    villager_uuid: str,
    profession: str,
) -> bool

Set a villager's profession

Parameters

villager_uuidstrrequired

Villager entity UUID string

professionstrrequired

Profession name. Valid values are: ARMORER, BUTCHER, CARTOGRAPHER, CLERIC, FARMER, FISHERMAN, FLETCHER, LEATHERWORKER, LIBRARIAN, MASON, NITWIT, NONE, SHEPHERD, TOOLSMITH, WEAPONSMITH

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found, not a villager, or invalid profession

Example

>>> uuid = mc.summon("villager", 100, 64, 200)
>>> mc.setVillagerProfession(uuid, "LIBRARIAN")
True

Sent as setVillagerProfessionclient.py line 1033

setVillagerTrades

mc.setVillagerTrades(
    villager_uuid: str,
    trades: list,
) -> bool

Set custom trades for a villager (replaces all existing trades)

Parameters

villager_uuidstrrequired

Villager entity UUID string

tradeslistrequired

List of trade definitions. Each trade is a dictionary with:

  • buy1: {"item": str, "amount": int} - First ingredient (required)
  • buy2: {"item": str, "amount": int} - Second ingredient (optional)
  • sell: {"item": str, "amount": int} - Result item (required)
  • max_uses: Maximum number of uses (default: 10)
  • experience_reward: Whether to give XP (default: True)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If entity not found, not a villager, or invalid trade data

Example

>>> uuid = mc.summon("villager", 100, 64, 200)
>>> mc.setVillagerProfession(uuid, "LIBRARIAN")
>>> mc.setVillagerTrades(uuid, [
...     {
...         "buy1": {"item": "emerald", "amount": 10},
...         "sell": {"item": "diamond_sword", "amount": 1},
...         "max_uses": 5
...     },
...     {
...         "buy1": {"item": "emerald", "amount": 5},
...         "buy2": {"item": "book", "amount": 1},
...         "sell": {"item": "enchanted_book", "amount": 1},
...         "max_uses": 10
...     }
... ])
True

Sent as setVillagerTradesclient.py line 1062

Scoreboards, teams & boss bars

Objectives, scores, display slots, teams and boss bars.

addObjective

mc.addObjective(
    name: str,
    criteria: str,
    display_name: str = None,
) -> bool

Add a scoreboard objective

Parameters

namestrrequired

Objective name

criteriastrrequired

Criteria (e.g., "dummy", "playerKillCount")

display_namestr= None

Display name (default: same as name)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If objective already exists

Example

>>> mc.addObjective("kills", "playerKillCount", "Player Kills")
True

Sent as addObjectiveclient.py line 1844

removeObjective

mc.removeObjective(name: str) -> bool

Remove a scoreboard objective

Parameters

namestrrequired

Objective name

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If objective not found

Example

>>> mc.removeObjective("kills")
True

Sent as removeObjectiveclient.py line 1870

setScore

mc.setScore(
    objective: str,
    player: str,
    score: int,
) -> bool

Set a player's score for an objective

Parameters

objectivestrrequired

Objective name

playerstrrequired

Player name or entity name

scoreintrequired

Score value

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If objective not found

Example

>>> mc.setScore("kills", "Steve", 10)
True

Sent as setScoreclient.py line 1891

getScore

mc.getScore(objective: str, player: str) -> int

Get a player's score for an objective

Parameters

objectivestrrequired

Objective name

playerstrrequired

Player name or entity name

Returns

int Score value

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If objective not found

Example

>>> mc.getScore("kills", "Steve")
10

Sent as getScoreclient.py line 1914

setDisplaySlot

mc.setDisplaySlot(
    slot: str,
    objective: str = None,
) -> bool

Set which objective is displayed in a display slot

Parameters

slotstrrequired

Display slot ("below_name", "sidebar", "player_list")

objectivestr= None

Objective name, or None to clear the slot

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid slot or objective not found

Example

>>> mc.setDisplaySlot("sidebar", "kills")
True
>>> mc.setDisplaySlot("sidebar")  # Clear sidebar
True

Sent as setDisplaySlotclient.py line 1936

team

mc.team(
    action: str,
    name: str = None,
    members: List[str] = None,
    option: str = None,
    value: str = None,
    display_name: str = None,
) -> dict

Manage scoreboard teams

Parameters

actionstrrequired

Action ("add", "remove", "join", "leave", "modify", "list")

namestr= None

Team name (required for most actions)

membersList[str]= None

List of player names (for join/leave)

optionstr= None

Option name for modify (displayname, color, friendlyfire, seefriendlyinvisibles, prefix, suffix)

valuestr= None

Value for modify action

display_namestr= None

Display name for add action

Returns

dict Dictionary with team information

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If team not found or invalid action

Example

>>> mc.team("add", "red_team", display_name="Red Team")
{'name': 'red_team'}
>>> mc.team("join", "red_team", members=["Steve", "Alex"])
{'added': 2}
>>> mc.team("modify", "red_team", option="color", value="RED")
{'modified': True}
>>> mc.team("list")
{'teams': [...]}

Sent as teamclient.py line 2028

bossbar

mc.bossbar(
    action: str,
    bar_id: str,
    title: str = None,
    color: str = None,
    style: str = None,
    progress: float = None,
    visible: bool = None,
    username: str = None,
) -> dict

Manage boss bars

Bars are kept in the plugin's memory (not vanilla /bossbar ids), so they disappear when the server restarts. On "add", an unknown color or style falls back to WHITE / SOLID; on "set" it raises CommandError.

Parameters

actionstrrequired

Action ("add", "remove", "set", "addplayer", "removeplayer", "get", "list")

bar_idstrrequired

Boss bar ID (required for every action; any value works for "list")

titlestr= None

Bar title (for add/set)

colorstr= None

Bar color (WHITE, PINK, BLUE, RED, GREEN, YELLOW, PURPLE) (for add/set)

stylestr= None

Bar style (SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20) (for add/set)

progressfloat= None

Progress value 0.0-1.0 (for add/set)

visiblebool= None

Visibility (for add/set)

usernamestr= None

Player name (for addplayer/removeplayer)

Returns

dict Dictionary with boss bar information

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If boss bar not found or invalid action

Example

>>> mc.bossbar("add", "my_bar", title="Boss Fight", color="RED")
{'id': 'my_bar'}
>>> mc.bossbar("addplayer", "my_bar", username="Steve")
{'added': True}
>>> mc.bossbar("set", "my_bar", progress=0.5)
{'updated': True}

Sent as bossbarclient.py line 2072

World generation

Locate structures, generate loot, paint biomes and place features, structures and templates.

locate

mc.locate(
    structure: str,
    x: float = None,
    z: float = None,
) -> dict

Locate the nearest structure

Searches the first (main) world within 100 chunks of the start point.

Parameters

structurestrrequired

Structure key (e.g., "village_plains", "minecraft:desert_pyramid", "ancient_city"). Structure tags such as "village" are not accepted.

xfloat= None

Search from X coordinate (default: world spawn)

zfloat= None

Search from Z coordinate (default: world spawn)

Returns

dict Dictionary with found (bool) and x, y, z if found. The coordinates point at the structure's chunk; y is not a ground height (usually 0).

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid structure type

Example

>>> mc.locate("village_plains")
{'found': True, 'x': 16, 'y': 0, 'z': 112}

Sent as locateclient.py line 2235

loot

mc.loot(
    loot_table: str,
    x: float,
    y: float,
    z: float,
) -> int

Generate loot from a loot table and drop it at a location

Parameters

loot_tablestrrequired

Loot table name (e.g., "chests/simple_dungeon")

xfloatrequired

X coordinate

yfloatrequired

Y coordinate

zfloatrequired

Z coordinate

Returns

int Number of items generated

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid loot table

Example

>>> mc.loot("chests/simple_dungeon", 100, 64, 200)
5

Sent as lootclient.py line 2295

fillbiome

mc.fillbiome(
    x1: int,
    y1: int,
    z1: int,
    x2: int,
    y2: int,
    z2: int,
    biome: str,
    filter_biome: str = None,
) -> bool

Fill a region with a specific biome

Runs the vanilla ``fillbiome`` command. The region must be loaded, and vanilla rejects very large regions; such failures (like "That position is not loaded") are only reported in the server log.

Parameters

x1intrequired

Start X coordinate

y1intrequired

Start Y coordinate

z1intrequired

Start Z coordinate

x2intrequired

End X coordinate

y2intrequired

End Y coordinate

z2intrequired

End Z coordinate

biomestrrequired

Target biome (e.g., "minecraft:plains")

filter_biomestr= None

Only replace this biome (optional)

Returns

bool True once the command was dispatched

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If the biome name is invalid

Example

>>> mc.fillbiome(100, 60, 200, 115, 75, 215, "minecraft:desert")
True

Sent as fillbiomeclient.py line 2322

placeFeature

mc.placeFeature(
    feature: str,
    x: int = None,
    y: int = None,
    z: int = None,
) -> bool

Place a configured feature at a location

Runs the vanilla ``place feature`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.

Parameters

featurestrrequired

Feature name (e.g., "minecraft:oak")

xint= None

X coordinate (optional)

yint= None

Y coordinate (optional)

zint= None

Z coordinate (optional)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid feature

Example

>>> mc.placeFeature("minecraft:oak", 100, 64, 200)
True

Sent as placeFeatureclient.py line 2361

placeStructure

mc.placeStructure(
    structure: str,
    x: int = None,
    y: int = None,
    z: int = None,
) -> bool

Place a structure at a location

Runs the vanilla ``place structure`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.

Parameters

structurestrrequired

Structure name (e.g., "minecraft:village_plains")

xint= None

X coordinate (optional)

yint= None

Y coordinate (optional)

zint= None

Z coordinate (optional)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid structure

Example

>>> mc.placeStructure("minecraft:village_plains", 100, 64, 200)
True

Sent as placeStructureclient.py line 2393

placeJigsaw

mc.placeJigsaw(
    pool: str,
    target: str,
    max_depth: int,
    x: int = None,
    y: int = None,
    z: int = None,
) -> bool

Place a jigsaw structure pool at a location

Runs the vanilla ``place jigsaw`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.

Parameters

poolstrrequired

Jigsaw pool name

targetstrrequired

Target name

max_depthintrequired

Maximum depth (1-20)

xint= None

X coordinate (optional)

yint= None

Y coordinate (optional)

zint= None

Z coordinate (optional)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid pool or parameters

Example

>>> mc.placeJigsaw("minecraft:village/plains/houses", "minecraft:empty", 7, 100, 64, 200)
True

Sent as placeJigsawclient.py line 2425

placeTemplate

mc.placeTemplate(
    template: str,
    x: int = None,
    y: int = None,
    z: int = None,
    rotation: str = 'none',
    mirror: str = 'none',
    integrity: float = 1.0,
    seed: int = 0,
) -> bool

Place a structure template at a location

Runs the vanilla ``place template`` command. The target chunk must be loaded; vanilla failures are only reported in the server log.

Parameters

templatestrrequired

Template name

xint= None

X coordinate (optional)

yint= None

Y coordinate (optional)

zint= None

Z coordinate (optional)

rotationstr= 'none'

Rotation (none, clockwise_90, 180, counterclockwise_90)

mirrorstr= 'none'

Mirror mode (none, front_back, left_right)

integrityfloat= 1.0

Structure integrity 0.0-1.0 (default: 1.0)

seedint= 0

Random seed for integrity (default: 0)

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If invalid template

Example

>>> mc.placeTemplate("my_house", 100, 64, 200, rotation="clockwise_90")
True

Sent as placeTemplateclient.py line 2463

Server

Run any command, list online players and spread players across the map.

exec

mc.exec(command: str) -> bool

Execute any Minecraft command on the server

A universal command executor that can run any Minecraft command. Useful for commands not yet wrapped as dedicated methods.

The command runs as the server console. Its output (including vanilla errors such as "No player was found") only appears in the server log.

Parameters

commandstrrequired

The command to execute (with or without leading /)

Returns

bool True if the server found and ran the command (even if the command itself reported a failure), False if the command does not exist

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If command execution fails

Example

>>> mc.exec("seed")
True
>>> mc.exec("/say Hello World")
True

Sent as execclient.py line 1281

list

mc.list() -> dict

Get list of online players

Returns

dict Dictionary with online_count, max_players, and players list

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails

Example

>>> mc.list()
{'online_count': 2, 'max_players': 20, 'players': [{'name': 'Steve', ...}]}

Sent as listclient.py line 2592

spreadplayers

mc.spreadplayers(
    center_x: float,
    center_z: float,
    spread_distance: float,
    max_range: float,
    usernames: List[str],
) -> bool

Spread players randomly around a center point

Runs the vanilla ``spreadplayers`` command (respectTeams = false); vanilla failures are only reported in the server log.

Parameters

center_xfloatrequired

Center X coordinate

center_zfloatrequired

Center Z coordinate

spread_distancefloatrequired

Minimum distance between players

max_rangefloatrequired

Maximum distance from center

usernamesList[str]required

List of player usernames to spread

Returns

bool True if successful

Raises

  • ConnectionError If connection fails
  • AuthenticationError If authentication fails
  • CommandError If players not found or invalid parameters

Example

>>> mc.spreadplayers(0, 0, 10, 100, ["Steve", "Alex"])
True

Sent as spreadplayersclient.py line 2535