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

pterodactyl-mcp

pterodactyl-mcp

Features

Quick Start

Configuration

Usage with Claude Desktop / Claude Code / Cursor

Hosted Mode (Cloudflare Worker)

Available Tools (42)

Server Management (Application API)

Power Control (Client API)

Console (Client API)

File Management (Client API)

Backups (Client API)

Startup & Config (Client API)

Schedules (Client API)

Databases (Client API)

Sub-users (Client API)

Account (Client API)

Users (Application API)

Nodes (Application API)

Panel Config (Application API)

Important: Server ID vs Identifier

Getting API Keys

Development

Contributing

License

Reviews