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.
- 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
npx @zefarie/pterodactyl-mcpSet 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 |
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.
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.
| 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 |
| 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 |
| Tool | Description | Type |
|---|---|---|
send_command |
Send a console command to a running server | Destructive |
| 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 |
| Tool | Description | Type |
|---|---|---|
list_backups |
List all backups for a server | Read-only |
create_backup |
Create a new server backup | Destructive |
| Tool | Description | Type |
|---|---|---|
get_startup_variables |
Get startup command, env variables, and Docker images | Read-only |
| Tool | Description | Type |
|---|---|---|
list_schedules |
List all scheduled tasks (cron jobs) for a server | Read-only |
| Tool | Description | Type |
|---|---|---|
list_client_databases |
List databases for a server (client view) | Read-only |
| Tool | Description | Type |
|---|---|---|
list_subusers |
List sub-users with permissions for a server | Read-only |
| Tool | Description | Type |
|---|---|---|
get_account |
Get the current authenticated user's account info | Read-only |
| 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 |
| 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 |
| 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.
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.
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.
pnpm install # Install dependencies
pnpm build # Build the project
pnpm test # Run unit tests
pnpm lint # Run linter and formatter
pnpm typecheck # Type checkingContributions are welcome! Please make sure pnpm lint, pnpm typecheck, and pnpm test all pass before submitting.
MIT