MCPy Server

MCPy is a high-performance Minecraft server engine built with Python and Cython. It delivers an event-driven core, a scalable world system, zero-overhead networking, and robust persistence, enabling you to run and customize a Minecraft server with strong performance and flexible tooling.

How to use

You run the MCP server through a standard Python invocation and connect your MCP client to the server using the configured network port. Start the server with a base configuration, then tailor world, performance, and debug settings to fit your hosting environment. You can enable additional features like performance optimizations or debugging to diagnose issues during development and testing.

How to install

Prerequisites ensure you have the necessary runtime and dependencies to build and run the server.

# Prerequisites
python3 --version
python3 -m venv .venv
# Activate the virtual environment (example for Linux/macOS)
source .venv/bin/activate
# Or for Windows
.venv\Scripts\activate
python -m pip install --upgrade pip

# Install required packages
pip install -r _requirements.txt
pip install -e ".[dev]"
pip install -e ".[ai]"  # Optional: Enable AI features

# Dependency checks and build
python check_dependencies.py
python setup.py build_ext --inplace

Configuration and running tips

Configure how the server starts, including the world to load, the maximum number of players, and debugging or performance modes. The most common runtime command is shown below, which starts the server and loads a specific world with a custom configuration.

python -m mcpy.server --config custom_config.toml --world my_world --port 25565 --max-players 100

Operational notes

• The server exposes a configurable HTTP-based admin interface and a local stdio-based start mode. Use an environment-appropriate configuration for production, including database settings and backup schedules.

• For development, you can enable a verbose log and debugging output to trace issues, then switch back to normal operation once you’ve resolved the problems.

Available tools

server_run

Launch the MCP server using Python's module runner to start the core server process.

config_options

Provide and modify runtime options via command line flags or configuration files to tailor performance, world handling, and monitoring.

monitoring_integration

Enable Prometheus and Grafana integration for real-time server metrics and dashboards.

plugin_system

Extend server functionality with a plugin framework to add commands, events, and custom behavior.

persistence

Manage transactional world saving and efficient chunk serialization through the configured database backend.