Skip to main content
Glama

MCPy

by magi8101

MCPy: High-Performance Minecraft Server Engine


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

MetricTarget Value
Scalability20 TPS with 100+ concurrent players
Memory Usage<2 GB for 10,000 chunks
Latency<50 ms per player action
Reliability100% test coverage for core modules
Throughput10,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
OptionDescription
--config PATHPath to TOML config file
--world PATHWorld directory
--port NUMBERNetwork port (default: 25565)
--max-players NUMBERMax players (default: 20)
--view-distance NUMBERChunk view distance (default: 10)
--performance-modeExtra performance optimizations
--debugEnable debug mode
--log-level LEVELSet log level (default: info)
--backupEnable 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 -
                    Python
                  • -
                    security
                    A
                    license
                    -
                    quality
                    A Model Context Protocol server that enables seamless execution of commands, Python code, web content fetching, and reusable task management with secure credentials handling.
                    Last updated -
                    2
                    Python
                    MIT License
                    • Apple
                  • -
                    security
                    F
                    license
                    -
                    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 -
                    2
                    Python
                  • 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 -
                    14
                    131
                    TypeScript
                    Apache 2.0
                    • Apple

                  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