Pterodactyl MCP

A standalone, self-hosted MCP server for Pterodactyl Application and Client APIs.

Run one process per panel. Application and Client keys remain separate, and writes require operator enablement. Deployment bindings and credentials belong in your private infrastructure repository.

The coverage matrix lists every route in the pinned provider source, including exclusions and pending work. Standard tools cover server, user, node, allocation, location, nest, egg, database, backup, schedule, subuser, startup and file operations. Focused tools handle verified binary upload, file hashing and bounded console capture.

This is an initial implementation. Controlled-provider and SDK tests pass; live panels, ChatGPT connection, native file delivery and reconnect behavior require separate acceptance. No npm release has been published.

Run

Use Node 24.22.1 or a later Node 24 release.

npm ci --ignore-scripts
npm run check
npm start

Set these environment variables through your MCP launcher or secret manager:

Never place real keys in checked-in MCP configuration. An Application key does not substitute for a Client key. Provider permissions still apply. Console and binary transfer require explicit Wings origins; ordinary panel API reads do not.

The process speaks STDIO MCP. Its stdout contains only protocol messages. A private outbound MCP tunnel can launch it without exposing a public HTTP listener. Installing source locally does not connect ChatGPT cloud.

Related MCP server: Minecraft MCP Server

Tools

Discover IDs, inspect details, then pass the operation's path, query and body under input. Numeric Application server IDs differ from Client server identifiers. For example, ptero_read accepts:

{
  "operationId": "application.servers.list",
  "input": { "query": { "page": 2, "per_page": 25, "include": "node" } }
}

Pagination metadata is preserved. Fetch further pages explicitly. JSON key order has no significance; text file writes preserve raw UTF-8 contents.

Upload accepts server, directory, name, file.download_url and an optional expected sha256. The native file parameter is declared through openai/fileParams; actual host delivery remains an acceptance requirement. Artifact downloads accept HTTPS subdomains of oaiusercontent.com. Both upload and verification use provider-issued links to configured Wings origins, without forwarding the panel key. Files are bounded to 64 MiB and uploads are serialized within one server process. Upload verification reads back the exact destination and compares SHA-256; a failure after submission reports unknown completion.

Console capture defaults to three seconds and 100 lines. It is capped at 30 seconds, 200 lines and 24 KiB. Tokens remain internal. Expiring or invalid authentication closes capture; start a fresh call to obtain a new token.

Failure and data handling

The HTTP client verifies TLS, refuses redirects, bounds panel responses to 2 MiB and uses a 15-second panel deadline. File transfers have a two-minute overall deadline. Cancellation reaches provider requests; it cannot undo a submitted mutation. The server never automatically replays uncertain writes. Inspect provider state before retrying completion_unknown.

Tool results are capped at 64 KiB. Reduce pagination or includes when a result is too large. Known password/token/secret fields and environment values are omitted from structured responses. This is not general secret detection: arbitrary filenames, console text and file contents can contain sensitive data. Use private connections and grant the provider credentials only the intended permissions. Mutation annotations help the host request approval; they do not replace its approval policy or provider authorization.

Verify and contribute

npm run check runs formatting, lint, strict types, independent route drift, generated coverage-matrix drift and tests with coverage thresholds. CI runs on Linux and Windows and consumes BASIC's pinned shared quality checker. npm run smoke:package installs the packed artifact with production dependencies in a clean directory and performs a real STDIO handshake and discovery.

Tests contain synthetic data. Every executable catalogue operation has an independent SDK-to-HTTP request contract. The pinned provider routes and their license are under spec/; use npm run generate:routes and npm run generate:coverage when updating them. Live tests require separately approved disposable targets. Keep credentials and deployment automation out of public CI.

See the design for boundaries and prior art. This project has independent source and releases; it is not a fork of a community MCP.