🎮 Minecraft MCP Server (Pterodactyl Panel Integration)

An intelligent Model Context Protocol (MCP) server that empowers AI agents (Antigravity, Claude Desktop, Cursor, etc.) to manage, configure, and operate Minecraft servers hosted on Pterodactyl panels.

Built-in support for:

• 🛡️ Cloudflare Turnstile / Challenge Bypass (via undetected-chromedriver)

• ⏱️ Automatic Request Pacing & Rate Limiting to prevent 429/504 gateway timeouts

• 🧠 Pre-packaged Agent Skills (request-pacing and minecraft-server-management)

🚀 Features & Tools

Related MCP server: 1Panel MCP Server

📦 Requirements

• Python: 3.10 or higher

• Google Chrome installed (required by undetected-chromedriver for Cloudflare-protected panels)

• A Pterodactyl Panel account with an API key

🛠️ Quick Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure Credentials

Copy .env.example to .env:

cp .env.example .env

Fill in your details in .env:

PTERO_URL=https://panel.yourserverhost.com
PTERO_KEY=ptlc_your_account_api_key_here
PTERO_SERVER=your_server_identifier_here

Where to get your credentials:

• PTERO_URL: The URL you use to log into your Pterodactyl panel.

• PTERO_KEY: In your panel, go to Account Settings -> API Credentials -> Create New. Copy the token (starts with ptlc_).

• PTERO_SERVER: Open your server on the panel. The URL looks like https://panel.yourhost.com/server/a1b2c3d4 — a1b2c3d4 is your server identifier.

⚙️ Connecting to AI Clients

Antigravity / Gemini CLI

Add this entry to your mcp_config.json:

{
  "mcpServers": {
    "minecraft": {
      "command": "python",
      "args": ["path/to/server.py"],
      "env": {
        "PTERO_URL": "https://panel.yourserverhost.com",
        "PTERO_KEY": "ptlc_your_api_key_here",
        "PTERO_SERVER": "your_server_identifier_here"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "minecraft": {
      "command": "python",
      "args": ["<FULL_PATH_TO_SERVER.PY>"],
      "env": {
        "PTERO_URL": "https://panel.yourserverhost.com",
        "PTERO_KEY": "ptlc_your_api_key_here",
        "PTERO_SERVER": "your_server_identifier_here"
      }
    }
  }
}

🧠 Included Agent Skills

This repository includes custom agent skills in .agents/skills/:

• request-pacing: Enforces rate limiting, backoff, and respectful intervals to prevent hitting Cloudflare or panel limits.

• minecraft-server-management: Guidance for agents handling server power cycles, config edits, and player position / respawn handling.

📄 License

MIT License. Free to use, adapt, and share.