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