MCPDactyl

MCP server for the Pterodactyl Panel, versions 1.x and 2.0. Manage servers, files, databases and more across multiple panels from one MCP server. Runs over stdio and Streamable HTTP, locally, in Docker, or as a remote server on Cloudflare Workers.

Panels are not baked into the install config — you add them at runtime and switch between them. MCPDactyl detects whether a panel runs 1.x or 2.0 and offers the tools that fit it.

Status: v0.1. The full Client API and Application (admin) API for 1.x and 2.0, plus the 2.0 Admin API (~230 tools on a 2.0 panel). 2.0 support follows the 2.0 beta documentation and has not been run against a live 2.0 panel yet; 1.x is the better-exercised path. See ARCHITECTURE.md for the design.

Install

Needs Node 20+ and pnpm.

git clone https://github.com/MrMirhan/mcpdactyl.git
cd mcpdactyl
pnpm install
pnpm build

Related MCP server: Pterodactyl MCP Server

Run (stdio)

node dist/index.js

Register it with an MCP client, using the absolute path of your clone. Claude Code:

claude mcp add mcpdactyl -- node /path/to/mcpdactyl/dist/index.js

Any client that reads an mcpServers config (Claude Desktop, Cursor, …):

{
  "mcpServers": {
    "mcpdactyl": { "command": "node", "args": ["/path/to/mcpdactyl/dist/index.js"] }
  }
}

Then add a panel from the chat with panel_add (see Panels).

Run (Streamable HTTP)

node dist/index.js --http --port 3000 --host 127.0.0.1
# endpoint: http://127.0.0.1:3000/mcp  (POST/GET/DELETE)

Each MCP session gets its own active-panel state; saved panels are shared via the config file. Set MCPDACTYL_HTTP_TOKEN to require Authorization: Bearer <token> on every request. Bind to a public host only behind auth/TLS — the panel registry is shared across clients (or use MCPDACTYL_STATELESS=1 so every call must carry inline creds).

A caller that acts for different people can pin each session to one panel instead: send x-ptero-base-url and x-ptero-client-key and/or x-ptero-application-key headers on the initialize request. That session talks to that panel only; nothing is read from or written to the shared store, and no key appears in a tool argument. With MCPDACTYL_SEALED=1 the tools also stop accepting baseUrl/clientKey/applicationKey arguments and panel_add, panel_remove and panel_use are not registered.

Docker (HTTP)

docker build -t mcpdactyl .
docker run -p 3000:3000 -e MCPDACTYL_HTTP_TOKEN=your-secret mcpdactyl

The image is a self-contained bundle (no node_modules). Seed panels with -e MCPDACTYL_PANELS='[{"name":"prod","baseUrl":"https://panel","clientKey":"ptlc_…"}]' or mount a config dir at ~/.config/mcpdactyl. Always set MCPDACTYL_HTTP_TOKEN when exposing the port. The image serves the client tools by default; add -e MCPDACTYL_TOOLS=all for the admin tools too.

Cloudflare Workers (remote, free tier)

worker/index.ts runs MCPDactyl as a remote MCP server via the agents McpAgent on a Durable Object (per-session active panel) with Workers KV for the shared panel registry. The WebSocket console tool is omitted on Workers (ws is Node-only). All other tools are identical — they reuse the same pteroRequest and tool modules.

npx wrangler kv namespace create PANELS   # replace REPLACE_WITH_YOUR_KV_NAMESPACE_ID in wrangler.jsonc
npx wrangler deploy                        # needs a Cloudflare account (free plan is enough)

Endpoint: https://<worker>.workers.dev/mcp (Streamable HTTP). Choose the surface with the MCPDACTYL_TOOLS var (wrangler.jsonc ships with all); seed read-only panels with an MCPDACTYL_PANELS secret or let clients panel_add at runtime (persisted to KV).

Protect the public endpoint with a bearer token. Set MCPDACTYL_HTTP_TOKEN as a secret and every request must send Authorization: Bearer <token> — otherwise anyone who reaches the URL can use stored panel keys:

npx wrangler secret put MCPDACTYL_HTTP_TOKEN   # paste a long random token

Claude's built-in remote-MCP connector expects OAuth, so for a bearer connect through mcp-remote, which injects the header:

{ "mcpServers": { "mcpdactyl": {
  "command": "npx",
  "args": ["mcp-remote", "https://<worker>.workers.dev/mcp", "--header", "Authorization: Bearer <token>"]
}}}

pnpm cf:check validates the build without deploying; pnpm cf:dev runs it locally.

Free-tier fit: Workers 100k req/day, Durable Objects on the free plan (SQLite), KV 100k reads + 1k writes/day — ample for a personal proxy. CPU limit (10ms/invocation) is fine because the work is I/O-bound (fetch to the panel).

Panels

No URL or key in the MCP config. Manage panels via tools:

• panel_add { name, baseUrl, clientKey?, applicationKey?, apiVersion?, makeDefault?, test? }

• panel_list — keys masked

• panel_use { name } — active panel for this session

• panel_test { name? } — validate keys and re-detect the panel's API version

• panel_remove { name }

Every panel-targeting tool also accepts panel (a saved name) or inline baseUrl + clientKey/applicationKey. Resolution order: inline > panel name > active > default.

Client API keys start with ptlc_, Application (admin) keys with ptla_. A tool fails clearly if the selected panel lacks the key type it needs.

Panel versions (1.x and 2.0)

Each panel's API version is detected the first time a version-bound tool needs it, from whether /api/admin/version exists (2.0) or not (1.x). With only an application key the check uses /api/application/tags. The answer is cached on the panel (detectedApiVersion); panel_test probes again, for a panel upgraded since. Pin it with apiVersion: "1" or "2" in panel_add (or in MCPDACTYL_PANELS) to skip detection.

The version decides what is offered and how a call is sent:

• 1.x: nest tools (admin_nest_list, admin_nest_get) are listed. admin_egg_list without nest collects every egg through the nests.

• 2.0: tag tools (admin_tag_list, admin_tag_get), admin_node_deployable and the whole Admin API (adminapi_*, 115 tools) are listed. admin_egg_list and admin_egg_get use the flat egg routes, and a nest id is mapped to its tag through legacy_nest_id.

• Unknown (not detected yet): both small sets are listed and the Admin API is not.

The tool list follows the active panel and the client is sent tools/list_changed when it changes. A tool that needs one version also checks it when called, since a call can name another panel, and says which version the panel runs. On 2.0 a root administrator's client key also works where an application key is asked for.

Storage & env

• Panels persist to ~/.config/mcpdactyl/panels.json (chmod 600).

• MCPDACTYL_CONFIG_DIR — override the config directory.

• MCPDACTYL_PANELS — JSON seed read at boot, never written to disk.

• MCPDACTYL_STATELESS=1 — disable persistence; every call must carry inline creds.

• MCPDACTYL_TRANSPORT=http|stdio, MCPDACTYL_HTTP_HOST, MCPDACTYL_HTTP_PORT, MCPDACTYL_HTTP_TOKEN — HTTP transport.

• MCPDACTYL_SEALED=1 — hide the credential arguments and the panel-switching tools (see Run (Streamable HTTP)).

• MCPDACTYL_TOOLS=client|admin|all — which API surface to expose (default client). Application tools need a ptla_ key (or, on 2.0, a root admin's ptlc_ key); the Admin API needs a root admin's ptlc_ key.

Tools

Panel: panel_add, panel_list, panel_use, panel_test, panel_remove.

Full Client API (all accept panel / inline creds):

• Servers: server_list, server_get, server_resources, server_power, server_command, server_activity

• Settings: server_startup_get, server_set_variable, server_rename, server_reinstall, server_docker_image

• Console: server_console_tail (WebSocket, bounded capture window)

• Files: files_list, files_read, files_write, files_rename, files_copy, files_mkdir, files_delete, files_compress, files_decompress, files_chmod, files_pull, files_download_url, files_upload_url

• Databases: db_list, db_create, db_rotate_password, db_delete

• Schedules: schedule_list, schedule_get, schedule_create, schedule_update, schedule_delete, schedule_execute, schedule_task_create, schedule_task_update, schedule_task_delete

• Network: network_list, network_assign, network_set_primary, network_set_notes, network_delete

• Backups: backup_list, backup_create, backup_get, backup_download_url, backup_restore, backup_toggle_lock, backup_delete

• Subusers: subuser_list, subuser_get, subuser_create, subuser_update, subuser_delete, permissions_list, and subuser_set_files (only for panels running an SFTP-permissions addon; it is a route the stock panel does not have)

• Account: account_get, account_activity, account_2fa_get, account_2fa_enable, account_2fa_disable, account_update_email, account_update_password, account_apikey_list, account_apikey_create, account_apikey_delete, account_sshkey_list, account_sshkey_create, account_sshkey_remove

Application API (admin, ptla_ key; opt-in via MCPDACTYL_TOOLS=admin or all):

• Users: admin_user_list, admin_user_get, admin_user_get_external, admin_user_create, admin_user_update, admin_user_delete

• Servers: admin_server_list, admin_server_get, admin_server_get_external, admin_server_create, admin_server_update_details, admin_server_update_build, admin_server_update_startup, admin_server_suspend, admin_server_unsuspend, admin_server_reinstall, admin_server_delete

• Server databases: admin_server_db_list, admin_server_db_get, admin_server_db_create, admin_server_db_reset_password, admin_server_db_delete

• Nodes: admin_node_list, admin_node_get, admin_node_deployable, admin_node_config, admin_node_create, admin_node_update, admin_node_delete, admin_node_alloc_list, admin_node_alloc_create, admin_node_alloc_delete

• Locations: admin_location_list, admin_location_get, admin_location_create, admin_location_update, admin_location_delete

• Nests & eggs: admin_nest_list, admin_nest_get (Pterodactyl 1.x only), admin_egg_list, admin_egg_get (pass nest on 1.x; omit it on 2.0)

• Tags (Pterodactyl 2.0, replace nests): admin_tag_list, admin_tag_get

Admin API (Pterodactyl 2.0 only, a root administrator's ptlc_ key; MCPDACTYL_TOOLS=admin or all): one adminapi_* tool per operation of /api/admin: users, servers (mounts, transfer, rebuild, suspension, databases, backups), nodes (allocations, tags, utilization, deploy token), locations, mounts, eggs (variables, scripts, export, import, catalog), tags, settings, database hosts, API keys, extensions and the panel version. The tools are generated from the OpenAPI document of the 2.0 docs: node scripts/gen-admin-api.mjs [openapi-v2.json | URL] rewrites src/tools/admin/definitions.ts. Query filters such as filter[name] are arguments named filter_name. Uploads (adminapi_install_extension, adminapi_import_egg, adminapi_update_egg_from_import) take the file as base64, or the JSON text itself for an egg.

Develop

pnpm typecheck         # tsc --noEmit
pnpm typecheck:worker  # the same for the Cloudflare Worker entry
pnpm lint              # biome
pnpm test              # vitest: request client, panel registry, version detection, tools, Admin API
pnpm build             # tsup -> dist/index.js
pnpm smoke             # end-to-end stdio test, no real panel needed
pnpm smoke:http        # end-to-end Streamable HTTP test
pnpm cf:check          # Worker build dry-run

CI (.github/workflows/ci.yml) runs all of these. node scripts/gen-admin-api.mjs regenerates the Admin API tools from the 2.0 OpenAPI document.

License

MIT, see LICENSE.