Provides tools for interacting with the Pterodactyl Panel API, enabling management of game servers, power states, files, backups, and administrative functions like user and node oversight.
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-mcpConfiguration
Set these environment variables:
Variable | Required | Description |
| Yes | Your Pterodactyl Panel URL |
| Yes | Application API key (starts with |
| No | Client API key (starts with |
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 all servers with ID, identifier, name, status, and limits | Read-only |
| Get detailed server config (limits, egg, container, allocations) | Read-only |
| Create a new server with egg, resources, and allocation | Destructive |
| Permanently delete a server and all its data | Destructive |
| Update server name, description, owner, or external ID | Destructive |
| Update resource limits (memory, CPU, disk, swap) | Destructive |
| Update startup command, Docker image, or egg | Destructive |
| Suspend a server (prevents users from starting it) | Destructive |
| Unsuspend a previously suspended server | Destructive |
| Reinstall server egg (wipes all files) | Destructive |
| List databases attached to a server (admin view) | Read-only |
Power Control (Client API)
Tool | Description | Type |
| Start a stopped server | Destructive |
| Stop a running server gracefully | Destructive |
| Restart a server (works running or stopped) | Destructive |
| Forcefully kill a server process (data loss risk) | Destructive |
| Get real-time CPU, memory, disk, network usage and power state | Read-only |
Console (Client API)
Tool | Description | Type |
| Send a console command to a running server | Destructive |
File Management (Client API)
Tool | Description | Type |
| List files and directories in a server's filesystem | Read-only |
| Read the contents of a text file | Read-only |
| Write content to a file (create or overwrite) | Destructive |
| Create a new directory | Destructive |
| Delete one or more files or folders | Destructive |
| Rename or move a file/folder | Destructive |
| Compress files into a .tar.gz archive | Destructive |
| Extract an archive file | Destructive |
Backups (Client API)
Tool | Description | Type |
| List all backups for a server | Read-only |
| Create a new server backup | Destructive |
Startup & Config (Client API)
Tool | Description | Type |
| Get startup command, env variables, and Docker images | Read-only |
Schedules (Client API)
Tool | Description | Type |
| List all scheduled tasks (cron jobs) for a server | Read-only |
Databases (Client API)
Tool | Description | Type |
| List databases for a server (client view) | Read-only |
Sub-users (Client API)
Tool | Description | Type |
| List sub-users with permissions for a server | Read-only |
Account (Client API)
Tool | Description | Type |
| Get the current authenticated user's account info | Read-only |
Users (Application API)
Tool | Description | Type |
| List all user accounts on the panel | Read-only |
| Get detailed info for a specific user | Read-only |
| Create a new user account | Destructive |
| Update a user's details | Destructive |
Nodes (Application API)
Tool | Description | Type |
| List all infrastructure nodes | Read-only |
| Get detailed info for a specific node | Read-only |
| Get Wings daemon configuration for a node | Read-only |
Panel Config (Application API)
Tool | Description | Type |
| List all available server templates (eggs) | Read-only |
| List all mount points | Read-only |
| 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:7server_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 checkingContributing
Contributions are welcome! Please make sure pnpm lint, pnpm typecheck, and pnpm test all pass before submitting.
License
MIT