Panel MCP

✨ Why

Running game servers means a lot of small, careful jobs: "why did the lobby crash at 3am?", "bump view-distance on survival and restart it after the countdown", "which plugin is spamming this error?". Panel MCP lets an AI assistant do those jobs through your panel, not around it:

• No API keys to paste anywhere. The client signs in with OAuth 2.1, the same way you sign in to the panel (password, 2FA, passkeys), and you pick what it may do on a consent screen.

• Never more than you. Every tool checks the same panel permission as the matching API endpoint. A subuser with console-only access gets console-only tools.

• Everything on the record. Each action lands in the panel's activity log once, as you, under the panel's own event names. It reads exactly like your own clicks.

• One click to cut it off. Account → Connected Apps lists every app with its access and last use. Remove one and its tokens die instantly.

• Runs in the panel process. No extra service, port, container or database: install the extension and add the URL to your client.

Related MCP server: pterodactyl-mcp

🧭 How it works

1. Your MCP client finds the authorization server through /.well-known/oauth-protected-resource and registers itself (dynamic client registration).

2. You sign in to the panel and approve the connection on a consent page that shows where you will be sent back to and lets you choose Read, Control and Change files and settings.

3. The client receives an access token (1 hour) and a rotating refresh token (30 days) and calls tools on /mcp (Streamable HTTP, JSON responses).

4. Each tool call is checked against the scopes you granted and your panel permissions, then runs through the panel's own action classes, so anything that hooks those actions (other extensions, activity logging) sees MCP calls too.

📦 Install

From a release (recommended). Download panel-mcp.pteroext from the latest release, then on the panel host:

cd /var/www/pterodactyl
php artisan p:extension:install /path/to/panel-mcp.pteroext --enable

That runs the extension's migration (four ext_panel_mcp_oauth_* tables) and publishes its frontend. Reload the panel in your browser.

From source. Build it against your panel's SDK (from a panel checkout where npm ci && npm run build has run):

git clone https://github.com/jackh54/pterodactyl-panel-mcp.git && cd pterodactyl-panel-mcp
mkdir -p .sdk && (cd /path/to/panel/packages/sdk && npm pack --pack-destination "$OLDPWD/.sdk")
mv .sdk/pterodactyl-sdk-*.tgz .sdk/pterodactyl-sdk.tgz
npm install && npm run build && npm test
cd /var/www/pterodactyl
php artisan p:extension:pack /path/to/pterodactyl-panel-mcp --output=/tmp/panel-mcp.pteroext
php artisan p:extension:install /tmp/panel-mcp.pteroext --enable

Behind nginx, make sure /.well-known/ requests reach PHP (the stock Pterodactyl nginx config already sends everything that is not a file to index.php). Behind Cloudflare or another proxy, keep request timeouts at 100 seconds or more: wait_for_console waits up to 90.

🔌 Connect an AI client

Your MCP server URL is your panel address plus /mcp:

https://panel.example.com/mcp

The client opens your panel, you sign in (if you aren't already) and approve. Connections show up under Account → Connected Apps.

🧰 Tools

50 built-in tools. Each one needs the scope shown and the panel permission the equivalent API endpoint requires. Admin tools only exist for root administrators; nobody else even sees them listed.

list_servers · servers you can see, with live state get_server · details, limits, allocations, variables, image choices get_console · recent console output wait_for_console · wait for a line (e.g. Done () list_files · read_file · search_files download_file · any file, base64 or a link inspect_archive · look inside a jar/zip, read plugin.yml, outline a .class list_schedules · get_activity list_backups · download_backup · a short-lived link list_allocations · ports and their notes list_databases · passwords only with Manage access get_ops_guide 🛡️ · your team's runbook query_database 🛡️ · read-only SQL

power_action · start, stop, restart, kill send_command · run a console command and return the new output run_schedule · trigger a schedule now create_backup · with a name, lock and ignore patterns

edit_file · exact search-and-replace edits write_file · create_folder rename_file · copy_file · delete_files compress_files · decompress_file pull_file · download a URL to the server upload_file · any file up to 4 MB create_upload_link · for bigger files set_startup_variable · set_docker_image save_schedule · delete_schedule save_schedule_task · delete_schedule_task update_server_config 🛡️ · limits, startup, image

restore_backup · over the files, or onto a clean server delete_backup · set_backup_lock add_allocation · update_allocation · remove_allocation create_database · returns the details for a plugin config rotate_database_password · delete_database rename_server · reinstall_server

🛡️ = root administrators only. query_database exists only when you configure a read-only database account; get_ops_guide answers once you install a guide.

Manage backups, ports and databases arrived in 1.1. Connections approved before that don't have it: remove the app under Connected Apps and connect again to tick the box. On panel builds older than an action a tool needs, that tool is simply not listed.

Every client also receives short instructions when it connects: read before changing, confirm before restarts or deletes, never run a plugin's reload command, never echo secrets. Add your own house rules under Admin → Extensions → Panel MCP.

🔒 Security

Panel MCP was written to be safe to point an AI at a production network.

Found a vulnerability? Please read SECURITY.md and report it privately.

⚙️ Configuration

Everything is optional. Settings go in the panel's .env (then php artisan config:clear).

In the admin area, Extensions → Panel MCP → Assistant holds extra instructions sent to every client.

The operations guide

Give your AI the same runbook your staff use. Write it as Markdown with numbered ## sections:

## 1. Ground rules
## 4. Restarts
## 7. Dangerous commands

Install it with php artisan panel-mcp:guide ops-guide.md. Clients are told to read it before changing anything; they can list the sections, open one (section: "4"), or search it. Never put passwords, tokens or keys in it.

Read-only SQL

CREATE USER 'panel_mcp_ro'@'127.0.0.1' IDENTIFIED BY 'a-long-random-password';
GRANT SELECT ON `luckperms`.* TO 'panel_mcp_ro'@'127.0.0.1';
GRANT SELECT ON `litebans`.* TO 'panel_mcp_ro'@'127.0.0.1';

PANEL_MCP_SQL_USERNAME=panel_mcp_ro
PANEL_MCP_SQL_PASSWORD=a-long-random-password
PANEL_MCP_SQL_DATABASES=luckperms,litebans

🧩 Add your own tools

Other extensions can add tools to the MCP server. Implement PanelMcp\Contracts\ProvidesTools and tag the class:

use PanelMcp\Contracts\ProvidesTools;
use Pterodactyl\Models\User;

class NetworkTools implements ProvidesTools
{
    public function tools(): array
    {
        return [
            'get_player_count' => [
                'scope' => 'panel:read',
                'admin' => false,
                'title' => 'Player count',
                'description' => 'Players online across the network right now.',
                'properties' => [],
                'required' => [],
                'run' => fn (array $args, User $user, object $grant) => ['online' => 42],
            ],
        ];
    }
}

// In your extension provider's register() or boot():
$this->app->tag([NetworkTools::class], 'panel-mcp.tools');

Tagging only stores the class name, so your extension keeps working when Panel MCP isn't installed. Built-in tool names win (unless this panel build can't offer that built-in), malformed tools are skipped and logged, and your tool does its own permission checks (throw PanelMcp\ToolException to return an error).

🧪 Development

npm install && npm run build   # frontend (Connected Apps card)
npm test && npx tsc            # unit tests and types
php tests/upstream-classes.php ../panel   # every panel class the extension uses still exists

tests/e2e holds an end-to-end suite of about 530 checks that drives the OAuth flow and every tool over real HTTP against a local dev panel with a fake Wings node. See tests/e2e/README.md.

📄 License

MIT © PandaScript. Not affiliated with or endorsed by Pterodactyl Software.