@namkrub/pterodactyl-mcp

A client-key friendly MCP server for Pterodactyl Panel.

This fork is based on @zefarie/pterodactyl-mcp and adds compatibility changes for local AI clients:

• Three auth modes: client-only, admin-only, or dual-key
• Legacy Python-style environment aliases: PTERO_URL and PTERO_KEY
• MCP stdio compatibility for clients that send Content-Length framed messages
• JSONL responses for clients that parse one JSON-RPC message per line

Features

• Client-only mode with PTERODACTYL_CLIENT_KEY for power, files, console, backups, schedules, databases, and account info
• Admin-only mode with PTERODACTYL_APP_KEY for panel-wide server, node, user, egg, nest, allocation, and mount management
• Dual-key mode with both keys for the full toolset
• 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 @namkrub/pterodactyl-mcp

Configuration

Set these environment variables:

| Variable | Required | Description | |----------|----------|-------------| | PTERODACTYL_URL | Yes | Your Pterodactyl Panel URL | | PTERODACTYL_CLIENT_KEY | Yes, unless app key is set | Client API key (starts with ptlc_) for power/files/console tools | | PTERODACTYL_APP_KEY | Optional | Application API key (starts with ptla_) for admin tools | | PTERO_URL | Alias | Legacy alias for PTERODACTYL_URL | | PTERO_KEY | Alias | Legacy alias for PTERODACTYL_CLIENT_KEY |

Auth Modes

Client-only

Use this for normal game-server operations scoped to the account that owns the Client API key.

Tools include power control, console commands, file management, backups, schedules, databases, subusers, logs, activity, and account info.

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

Admin-only

Use this for panel-wide administration. Requires a Pterodactyl Application API key.

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

Dual-key

Use this for the full toolset.

{
  "mcpServers": {
    "pterodactyl": {
      "command": "npx",
      "args": ["-y", "@namkrub/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.

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.

Getting API Keys

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

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

Development

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

License

MIT