/minecraft-mcp-gdpc

Build Minecraft worlds and structures with natural language via MCP

Primary LanguagePython

Minecraft MCP Server with GDPC and FastMCP

A powerful, extensible platform for programmatic Minecraft world generation and structure building using GDPC, FastMCP, and Supabase.

Overview

This project combines:

  • GDPC (Generative Design in Minecraft Python Client) for Minecraft world manipulation
  • FastMCP (FastAPI-based MCP server) for RESTful API endpoints
  • Supabase for database, authentication, and storage

The system enables programmatic creation and manipulation of Minecraft worlds, including terrain generation, structure building, and template management.

Features

  • World Generation: Create custom terrain using procedural algorithms
  • Structure Building: Design, save, and place structures using a blueprint system
  • Template Management: Share and discover building templates
  • Real-time Updates: Monitor long-running operations via WebSockets
  • User Authentication: Secure access control with Supabase Auth
  • API Access: RESTful API for integration with other tools

Getting Started

Prerequisites

Installation

  1. Set up Minecraft server with GDMC HTTP Interface mod

    See the implementation plan for detailed instructions

  2. Clone this repository

    git clone https://github.com/natea/minecraft-mcp-gdpc.git
cd minecraft-mcp-gdpc

  3. Create and activate a virtualenv

    python -m venv venv
source venv/bin/activate

  4. Install dependencies

    pip install -r requirements.txt

  5. Configure environment variables

    cp .env.example .env
# Edit .env with your Supabase credentials and other settings

  6. Run the server

    python src/main.py

Documentation

Architecture

The system follows a modular architecture with clear separation of concerns:

  1. FastMCP Server Layer: API gateway, authentication, and request handling (see FastMCP)
  2. GDPC Integration Layer: Interface with Minecraft worlds (see GDPC Python library)
  3. Supabase Integration Layer: Database, auth, and storage
  4. World Generation Features: Terrain algorithms and biome management
  5. Structure Building System: Blueprint format and component library

See the architecture diagram for a visual representation.

Development

Project Structure

minecraft-mcp-gdpc/
├── docs/                       # Documentation
├── src/                        # Source code
│   ├── api/                    # FastMCP API endpoints
│   ├── gdpc_interface/         # GDPC integration layer
│   ├── world_gen/              # World generation algorithms
│   ├── structures/             # Structure building system
│   └── supabase/               # Supabase integration
├── tests/                      # Test suite
├── minecraft-server/           # Minecraft server files
├── config/                     # Configuration files
└── examples/                   # Example scripts and templates

Testing

# Run unit tests
pytest tests/unit

# Run integration tests
pytest tests/integration

# Run end-to-end tests
pytest tests/e2e

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the 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.

Acknowledgments