Skip to main content
Glama

MCPy

by magi8101

MCPy: High-Performance Minecraft Server Engine

License: MIT Python 3.9+ Cython


MCPy is a next-generation, ultra-optimized Minecraft server engine powered by Python, Cython, and advanced scientific computing libraries. Our mission is to deliver exceptional performance and flexibility, making Minecraft server development both accessible and future-proof.

Note:
MCPy is under active development and is not yet feature-complete. The codebase contains known errors and is unstable. We welcome your bug reports and contributions to help us reach our goals faster!


🚧 Project Status

  • The project is incomplete and contains known issues.

  • Major features are under active development; the codebase is unstable.

  • We highly value contributions and bug reports from the community.


🚀 Features at a Glance

  • Cython-Accelerated Core: Event-driven server engine approaching C-level performance.

  • Scientific Computing Backbone: Integrates NumPy, SciPy, and Polars for high-efficiency operations.

  • Zero-Overhead Networking: Asynchronous, non-blocking, protocol-optimized networking.

  • Sophisticated Entity System: Efficient, extensible entity management with advanced AI support.

  • Robust Persistence Layer: Powered by PostgreSQL and SQLAlchemy ORM for reliable data storage.

  • Comprehensive Benchmarking: Built-in performance analytics and profiling tools.

  • Extensible Plugin Framework: Easily add server modifications.

  • Real-Time Monitoring: Prometheus & Grafana integration for live metrics.


📐 Architecture Overview

MCPy is modular, with five high-performance core components:

  1. server_core.pyx

    • Event-driven request handling

    • Adaptive, high-precision tick system

    • Dynamic worker thread pool management

    • Real-time performance profiling

  2. world_engine.pyx

    • Procedural terrain generation with multi-octave noise and advanced biomes

    • Multi-threaded chunk generation & memory-efficient terrain storage

  3. network_core.pyx

    • Zero-copy packet serialization and protocol-level compression

    • Robust connection pooling & DDoS mitigation

  4. entity_system.pyx

    • Spatial hash-based entity tracking and multi-threaded physics

    • Modular AI behavior trees

  5. persistence

    • SQLAlchemy ORM for PostgreSQL/SQLite

    • Efficient chunk serialization and transactional world state


📊 Performance Goals

Metric

Target Value

Scalability

20 TPS with 100+ concurrent players

Memory Usage

<2 GB for 10,000 chunks

Latency

<50 ms per player action

Reliability

100% test coverage for core modules

Throughput

10,000+ entity updates per tick


⚙️ Technical Highlights

Cython & Performance

  • Static typing (cdef) and aggressive compiler directives

  • Direct NumPy buffer access and pointer arithmetic

  • Multi-threaded parallelism via thread pools

Entity System

  • Hierarchical, component-based design

  • O(1) spatial partitioning via custom memory pools

  • Adaptive Level-of-Detail (LOD) entity management

World Generation

  • Multi-octave Perlin/Simplex noise

  • Voronoi-based biome transitions

  • Erosion, cave, and structure algorithms

  • 10x chunk compression for storage efficiency


📦 Installation

Prerequisites

  • Python 3.9+ (3.11+ recommended)

  • Modern C++ compiler (VS 2019+ / GCC 9+)

  • PostgreSQL 13+ (for production)

  • Minimum 8 GB RAM (16 GB recommended)

Quick Setup

git clone https://github.com/magi8101/mcpy.git cd mcpy # Windows setup.bat # Linux/macOS chmod +x setup.sh ./setup.sh

Manual Installation

git clone https://github.com/magi8101/mcpy.git cd mcpy python -m venv .venv # Windows: .venv\Scripts\activate # Linux/macOS: source .venv/bin/activate pip install -r _requirements.txt pip install -e ".[dev]" pip install -e ".[ai]" # Optional: Enable AI features python check_dependencies.py python setup.py build_ext --inplace

🚀 Running the Server

# Using setup scripts # Windows: setup.bat run # Linux/macOS: ./setup.sh run # Directly from the command line python -m mcpy.server python -m mcpy.server --config custom_config.toml --world my_world python -m mcpy.server --performance-mode --max-players 100 python -m mcpy.server --debug --log-level debug

Command Line Options

Option

Description

--config PATH

Path to TOML config file

--world PATH

World directory

--port NUMBER

Network port (default: 25565)

--max-players NUMBER

Max players (default: 20)

--view-distance NUMBER

Chunk view distance (default: 10)

--performance-mode

Extra performance optimizations

--debug

Enable debug mode

--log-level LEVEL

Set log level (default: info)

--backup

Enable automatic backups


🗄️ Database Configuration

SQLite (Default)

[database] type = "sqlite" path = "world/mcpy.db" journal_mode = "WAL" synchronous = "NORMAL"

PostgreSQL (Production)

[database] type = "postgresql" host = "localhost" port = 5432 dbname = "mcpy" user = "postgres" password = "your_password" pool_size = 10 max_overflow = 20 echo = false

💾 Persistence Features

  • Transactional World Saving

    with session.begin(): for chunk in dirty_chunks: session.add(ChunkModel.from_chunk(chunk))
  • Efficient Chunk Serialization

    chunk_data = np.savez_compressed(io_buffer, blocks=chunk.blocks, heightmap=chunk.heightmap, biomes=chunk.biomes)
  • Player Data Management

    player_model = PlayerModel( uuid=player.uuid, username=player.username, position=json.dumps([player.x, player.y, player.z]), inventory=pickle.dumps(player.inventory, protocol=5), stats=json.dumps(player.stats) )
  • Intelligent Auto-saving: Only modified chunks/entities are saved

  • Automated Backups: Configurable intervals & retention


🧪 Development & Testing

pytest # Run full test suite pytest tests/test_entity_system.py # Entity system tests python -m benchmarks.benchmark # Benchmarks python -m mcpy.profiling.profile_module world_engine # Profile module pytest --cov=mcpy --cov-report=html # Test coverage report

Performance Tuning Examples

  • Entity System

    entity_spatial_hash = {(int(e.x/16), int(e.z/16)): [] for e in entities} for entity in entities: entity_spatial_hash[(int(entity.x/16), int(entity.z/16))].append(entity)
  • World Engine

    with ThreadPoolExecutor(max_workers=os.cpu_count()) as executor: futures = [executor.submit(generate_chunk, x, z) for x, z in chunk_coords] chunks = [f.result() for f in futures]
  • Network Optimization

    cdef char* buffer = <char*>malloc(packet_size) memcpy(buffer, &packet_header, sizeof(packet_header)) memcpy(buffer + sizeof(packet_header), packet_data, packet_data_size)

🔧 Advanced Features

Plugin System

Add custom commands and behaviors easily:

from mcpy.plugins import Plugin, event class TeleportPlugin(Plugin): @event("player.command") def on_command(self, player, command, args): if command == "tp" and len(args) >= 1: target = self.server.get_player_by_name(args[0]) if target: player.teleport(target.x, target.y, target.z) return True return False

Real-time Monitoring

Integrated Prometheus/Grafana support:

[monitoring] enabled = true prometheus_port = 9090 metrics = ["tps", "memory_usage", "players_online", "chunks_loaded"]

AI Entity Behaviors

Flexible, behavior-tree-driven AI:

class ZombieAI(MobAI): def setup_behaviors(self): self.behaviors = BehaviorTree( Selector([ Sequence([ CheckPlayerNearby(radius=16), PathfindToPlayer(), AttackPlayer() ]), Sequence([ Wait(random.randint(20, 100)), MoveToRandomPosition(radius=10) ]) ]) )

🗺️ Roadmap

Short-Term

  • Entity collision system

  • Crafting & inventory management

  • Basic combat mechanics

  • World generation optimization

Medium-Term

  • Multi-world support & portals

  • Custom block behaviors

  • Enhanced mob AI

  • In-game scripting API

Long-Term

  • Distributed server architecture

  • Machine learning-driven mob AI

  • Real-time ray-traced lighting

  • Custom physics engine


🤝 Contributing

We welcome your contributions! Please see our Contributing Guide to get started:

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to your branch (git push origin feature/amazing-feature)

  5. Open a Pull Request


📄 License

This project is licensed under the MIT License. See the LICENSE file for details.


-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A next-generation Minecraft server engine built with Python and Cython, aiming to deliver exceptional performance and flexibility through advanced scientific computing libraries and optimized architecture.

  1. 🚧 Project Status
    1. 🚀 Features at a Glance
      1. 📐 Architecture Overview
        1. 📊 Performance Goals
          1. ⚙️ Technical Highlights
            1. Cython & Performance
            2. Entity System
            3. World Generation
          2. 📦 Installation
            1. Prerequisites
            2. Quick Setup
            3. Manual Installation
          3. 🚀 Running the Server
            1. Command Line Options
          4. 🗄️ Database Configuration
            1. SQLite (Default)
            2. PostgreSQL (Production)
          5. 💾 Persistence Features
            1. 🧪 Development & Testing
              1. Performance Tuning Examples
            2. 🔧 Advanced Features
              1. Plugin System
              2. Real-time Monitoring
              3. AI Entity Behaviors
            3. 🗺️ Roadmap
              1. 🤝 Contributing
                1. 📄 License

                  Related MCP Servers

                  • -
                    security
                    F
                    license
                    -
                    quality
                    This is an MCP server that facilitates building tools for interacting with various APIs and workflows, supporting Python-based development with potential for customizable prompts and user configurations.
                    Last updated -
                  • A
                    security
                    F
                    license
                    A
                    quality
                    A server implementation that enables remote Python code execution in Unreal Engine environments, featuring automatic Unreal node discovery and management through a multicast network.
                    Last updated -
                    1
                    4
                  • A
                    security
                    A
                    license
                    A
                    quality
                    A Minecraft MCP Server powered by Mineflayer API. It allows to control a Minecraft character in real-time, allowing AI assistants to build structures, explore the world, and interact with the game environment through natural language instruction
                    Last updated -
                    16
                    8
                    340
                    Apache 2.0
                    • Apple
                  • focMCP SDKofficial

                    -
                    security
                    -
                    license
                    -
                    quality
                    Provides tools and infrastructure for building fully on-chain Minecraft Protocol servers that enable developers to create decentralized gaming experiences using blockchain technology.

                  View all related MCP servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/magi8101/Mcpy'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server