PythonMC

PythonMC is a server-side Fabric mod that adds lightweight Python scripting to Minecraft 1.21.1.

It lets server owners write simple Python scripts for common automation, player messages, server events, and command-driven behavior without recompiling the mod.

Features

• Loads Python scripts from the server config folder.
• Starts and manages a local Python 3.8+ script host automatically.
• Provides server lifecycle, tick, and player connection events.
• Exposes a small API for logging, broadcasting, private messages, and server command execution.
• Includes /pythonmc admin commands for status, reloads, restarts, custom events, and quick Python snippets.
• Ships with an example script on first launch.

Requirements

• Minecraft 1.21.1
• Fabric Loader 0.18.4 or newer
• Fabric API
• Java 21
• Python 3.8 or newer installed on the server

Python must be available as python3 or python on the server PATH.

If Python is installed somewhere else, set one of these before launching Minecraft:

-Dpythonmc.python=/path/to/python

or:

PYTHONMC_PYTHON=/path/to/python

Installation

1. Install Fabric Loader for Minecraft 1.21.1.
2. Install Fabric API.
3. Put the PythonMC jar in the server mods folder.
4. Make sure Python 3.8+ is installed on the machine running the server.
5. Start the server once.

PythonMC will create this folder:

config/pythonmc/scripts

It will also create a starter script:

config/pythonmc/scripts/main.py

Writing Scripts

Scripts are normal .py files inside:

config/pythonmc/scripts

Files whose names start with _ are ignored. After editing scripts, reload them in-game or from the server console:

/pythonmc reload

Basic example:

import pythonmc_api as mc


def on_server_started(ctx):
    mc.log("PythonMC script loaded.")


def on_player_join(ctx):
    mc.tell(ctx["name"], "Welcome! This message came from PythonMC.")

Script API

Import the bundled API like this:

import pythonmc_api as mc

Available functions:

mc.log(message, level="info")
mc.broadcast(message)
mc.tell(player_name, message)
mc.execute(command)

mc.execute(command) runs a Minecraft server command as the server command source. Use it carefully.

Events

PythonMC calls functions in your scripts when matching events happen.

Supported event handlers:

def on_server_started(ctx): ...
def on_server_stopping(ctx): ...
def on_server_tick(ctx): ...
def on_player_join(ctx): ...
def on_player_leave(ctx): ...
def on_shutdown(ctx): ...
def on_event(event_name, ctx): ...

The ctx object contains event data. It supports both dictionary-style access and .get():

def on_player_join(ctx):
    player_name = ctx["name"]
    player_uuid = ctx.get("uuid")

Common player event fields:

name
uuid

Common server event fields:

players
max_players
tick
scripts_dir

Commands

All commands require permission level 4.

/pythonmc status
/pythonmc start
/pythonmc stop
/pythonmc restart
/pythonmc reload
/pythonmc py <python code>
/pythonmc event <event_name>

Command details:

• /pythonmc status shows whether the Python host is running and where scripts are loaded from.
• /pythonmc start starts the Python script host if it is stopped.
• /pythonmc stop stops the Python script host.
• /pythonmc restart restarts the Python script host.
• /pythonmc reload reloads scripts from config/pythonmc/scripts.
• /pythonmc py <python code> runs a Python snippet in the host process.
• /pythonmc event <event_name> sends a custom event to scripts.

Custom event example:

import pythonmc_api as mc


def on_event(event_name, ctx):
    if event_name == "maintenance":
        mc.broadcast("Server maintenance is starting soon.")

Then run:

/pythonmc event maintenance

Security Notes

PythonMC scripts run on the server machine with the permissions of the Minecraft server process.

Only install or write scripts you trust. A Python script can perform normal Python file and process operations, and mc.execute() can run Minecraft commands from the server command source.

For public or shared servers, restrict /pythonmc command access to trusted operators only.

Server Side Only

PythonMC is intended for server-side scripting. Clients do not need to install the mod when connecting to a server that uses it, unless your modpack or server setup requires matching mod lists.

Troubleshooting

If scripts do not start:

• Run /pythonmc status.
• Confirm Python 3.8+ is installed.
• Confirm python3 or python works from the same environment that launches the Minecraft server.
• Set -Dpythonmc.python=/path/to/python if needed.
• Check the server log for messages tagged with pythonmc or [python].

If script changes do not apply:

• Make sure the file is in config/pythonmc/scripts.
• Make sure the filename ends in .py.
• Make sure the filename does not start with _.
• Run /pythonmc reload.
• Check the server log for Python traceback output.