pterodactyl-mcp

The first MCP server for Pterodactyl Panel. Manage your game servers with AI.

An MCP (Model Context Protocol) server that exposes the Pterodactyl Panel API to LLMs. Connect Claude, Cursor, or any MCP-compatible client to your game server infrastructure and manage it through natural language.

Features

• 42 MCP tools covering server management, power control, file management, backups, users, nodes, and more
• Dual API key support - Application API (admin) + Client API (power, files, console)
• Read-only and destructive actions properly annotated so your AI client can warn before dangerous operations
• Rate limiting and retry logic built-in with exponential backoff
• TypeScript, fully typed with strict mode enabled
• Zod validation on all inputs for robust parameter checking
• Structured JSON responses optimized for LLM consumption
• Health check on startup to verify panel connectivity

Quick Start

npx @zefarie/pterodactyl-mcp

Configuration

Set these environment variables:

| Variable | Required | Description | |----------|----------|-------------| | PTERODACTYL_URL | Yes | Your Pterodactyl Panel URL | | PTERODACTYL_APP_KEY | Yes | Application API key (starts with ptla_) | | PTERODACTYL_CLIENT_KEY | No | Client API key (starts with ptlc_) for power/files/console tools |

Usage with Claude Desktop / Claude Code / Cursor

Add to your MCP configuration:

{
  "mcpServers": {
    "pterodactyl": {
      "command": "npx",
      "args": ["-y", "@zefarie/pterodactyl-mcp"],
      "env": {
        "PTERODACTYL_URL": "https://panel.example.com",
        "PTERODACTYL_APP_KEY": "ptla_xxxxxxxxxxxxx",
        "PTERODACTYL_CLIENT_KEY": "ptlc_xxxxxxxxxxxxx"
      }
    }
  }
}

See docs/SETUP.md for platform-specific config file locations and troubleshooting.

Hosted Mode (Cloudflare Worker)

You can also deploy pterodactyl-mcp as a Cloudflare Worker, giving each user a unique MCP endpoint URL without running anything locally. See the Cloudflare Worker Deployment section in the setup guide.

Available Tools (42)

Server Management (Application API)

| Tool | Description | Type | |------|-------------|------| | list_servers | List all servers with ID, identifier, name, status, and limits | Read-only | | get_server | Get detailed server config (limits, egg, container, allocations) | Read-only | | create_server | Create a new server with egg, resources, and allocation | Destructive | | delete_server | Permanently delete a server and all its data | Destructive | | update_server_details | Update server name, description, owner, or external ID | Destructive | | update_server_build | Update resource limits (memory, CPU, disk, swap) | Destructive | | update_server_startup | Update startup command, Docker image, or egg | Destructive | | suspend_server | Suspend a server (prevents users from starting it) | Destructive | | unsuspend_server | Unsuspend a previously suspended server | Destructive | | reinstall_server | Reinstall server egg (wipes all files) | Destructive | | list_server_databases | List databases attached to a server (admin view) | Read-only |

Power Control (Client API)

| Tool | Description | Type | |------|-------------|------| | start_server | Start a stopped server | Destructive | | stop_server | Stop a running server gracefully | Destructive | | restart_server | Restart a server (works running or stopped) | Destructive | | kill_server | Forcefully kill a server process (data loss risk) | Destructive | | get_server_resources | Get real-time CPU, memory, disk, network usage and power state | Read-only |

Console (Client API)

| Tool | Description | Type | |------|-------------|------| | send_command | Send a console command to a running server | Destructive |

File Management (Client API)

| Tool | Description | Type | |------|-------------|------| | list_files | List files and directories in a server's filesystem | Read-only | | read_file | Read the contents of a text file | Read-only | | write_file | Write content to a file (create or overwrite) | Destructive | | create_folder | Create a new directory | Destructive | | delete_files | Delete one or more files or folders | Destructive | | rename_file | Rename or move a file/folder | Destructive | | compress_files | Compress files into a .tar.gz archive | Destructive | | decompress_file | Extract an archive file | Destructive |

Backups (Client API)

| Tool | Description | Type | |------|-------------|------| | list_backups | List all backups for a server | Read-only | | create_backup | Create a new server backup | Destructive |

Startup & Config (Client API)

| Tool | Description | Type | |------|-------------|------| | get_startup_variables | Get startup command, env variables, and Docker images | Read-only |

Schedules (Client API)

| Tool | Description | Type | |------|-------------|------| | list_schedules | List all scheduled tasks (cron jobs) for a server | Read-only |

Databases (Client API)

| Tool | Description | Type | |------|-------------|------| | list_client_databases | List databases for a server (client view) | Read-only |

Sub-users (Client API)

| Tool | Description | Type | |------|-------------|------| | list_subusers | List sub-users with permissions for a server | Read-only |

Account (Client API)

| Tool | Description | Type | |------|-------------|------| | get_account | Get the current authenticated user's account info | Read-only |

Users (Application API)

| Tool | Description | Type | |------|-------------|------| | list_users | List all user accounts on the panel | Read-only | | get_user | Get detailed info for a specific user | Read-only | | create_user | Create a new user account | Destructive | | update_user | Update a user's details | Destructive |

Nodes (Application API)

| Tool | Description | Type | |------|-------------|------| | list_nodes | List all infrastructure nodes | Read-only | | get_node | Get detailed info for a specific node | Read-only | | get_node_config | Get Wings daemon configuration for a node | Read-only |

Panel Config (Application API)

| Tool | Description | Type | |------|-------------|------| | list_eggs | List all available server templates (eggs) | Read-only | | list_mounts | List all mount points | Read-only | | list_roles | List all admin roles | Read-only |

See docs/TOOLS.md for detailed documentation on each tool, including parameters and example responses.

Important: Server ID vs Identifier

Pterodactyl uses two different identifiers for servers:

• server_id (number) - Used by Application API (admin) tools. Example: 7
• server_identifier (string) - Used by Client API tools (power, files, console). Example: "a1b2c3d4"

Call list_servers first to get both values. The response includes both id (numeric) and identifier (string) for each server.

Getting API Keys

Application API Key (required, ptla_): Admin Panel > Application API > Create New

Client API Key (optional, ptlc_): Account > API Credentials > Create

See docs/SETUP.md for detailed instructions.

Development

pnpm install      # Install dependencies
pnpm build        # Build the project
pnpm test         # Run unit tests
pnpm lint         # Run linter and formatter
pnpm typecheck    # Type checking

Contributing

Contributions are welcome! Please make sure pnpm lint, pnpm typecheck, and pnpm test all pass before submitting.

License

MIT