List the game servers this Pterodactyl API key can access, with their short identifiers, node, primary allocation and resource limits.

Use this first when you do not already know a server identifier, or when a call fails with "not found" — every other ptero_* tool takes that identifier as its server argument.

This does NOT report whether a server is running: status here is the panel lifecycle field (installing/suspended/etc.) and is null for a normal server whether it is up or down. Call ptero_get_server_resources for the live power state.

Results are paginated by the panel (50 per page). Pass page to fetch further pages; has_more tells you whether any remain.

Get the full configuration of one server: name, node, panel lifecycle status, resource limits, feature limits, every network allocation (ip/port/notes, and which is primary), SFTP host and port, Docker image and the resolved startup command.

Use this to answer "how is this server configured", "what ports does it have", "how much memory is it allowed", or "what is it running".

This is static configuration. It does NOT tell you whether the server is up or what it is currently consuming — use ptero_get_server_resources for that. For the ports alone, ptero_list_allocations is narrower. Note that a port being allocated does not mean a service actually bound to it; confirm that in the console log or the relevant plugin config file.

Get the live power state and current resource usage of a server: whether it is running, memory and disk in use, CPU percentage, network bytes in and out, and process uptime.

Use this to answer "is the server up?", "what is the memory doing?" or "how long has it been up?". This is the tool that reports running vs offline — ptero_get_server reports panel lifecycle status, which is a different thing.

Figures are cached by the panel for about 20 seconds, so calling repeatedly in quick succession returns identical numbers; that is the cache, not a frozen server. cpu_absolute is a percentage across all cores (200 means two full cores), and compares against the limits.cpu from ptero_get_server. When the server is offline every figure is 0. This tool does not explain why something is wrong — use ptero_get_console_log for that.

Connect to the server's live console websocket and return the backlog it hands back on connect (the node's ring buffer, ~150 most recent lines by default) plus whatever new lines stream in during the collection window, then disconnect.

Pterodactyl has no "give me the last N lines" request over REST — this websocket round trip is the only way to read console output, and what you get is a live snapshot, not a query over history.

The buffer rolls over quickly: roughly an hour after boot the plugin startup lines are already gone from it. For boot-time or plugin-load output, use ptero_read_file on logs/latest.log instead — that has the full run history.

After calling ptero_send_console_command, you MUST call this tool to see what the command did: dispatching a command never returns its output by itself.

filter narrows the returned lines (case-insensitive substring, or a regex if it parses as one) without needing a wider window — e.g. filter: "geyser" to isolate Geyser lines in a busy log.

Send a command to the server console via the panel's command endpoint (the panel forwards it to the running process). This confirms DISPATCH ONLY — it does NOT return the command's output. Wings does not correlate console output with the command that produced it, so there is no request/response shape to report here, faked or otherwise: the output is asynchronous. Call ptero_get_console_log immediately afterwards (a window_seconds of 3-5 is usually enough) to read what the command did.

Do not use this to stop, restart or kill the server. A command like stop will shut it down, but ptero_set_power_state is the correct, guarded way to change power state and should be preferred for that.

The panel answers with HTTP 502 when the target server is offline, since console commands require a running server — that is reported back as an actionable error telling you to start the server with ptero_set_power_state first.

List one directory on the game server, relative to the server root. Returns each entry's name, full server-relative path, whether it is a file or a directory, size, unix mode, MIME type and last-modified time. Directories are listed first, then files, each group sorted by name.

Use this to find out what is actually on disk before reading or changing anything: which plugins are installed (plugins), which world folders exist, which log files are available (logs), or the exact spelling of a config path.

The path on each entry is the value other file tools want — pass it to ptero_read_file, or use it with ptero_delete_file.

This is not recursive: it lists one level. To go deeper, call it again with a child directory's path. It also does not return file contents — use ptero_read_file.

Read a text file from the game server, relative to the server root. Returns the contents plus the file size.

THIS IS THE WAY TO GET FULL BOOT-TIME OUTPUT. Read logs/latest.log. The live console (ptero_get_console_log) only keeps roughly the last 150 lines, so within an hour of boot the plugin startup lines — which port Geyser bound to, which plugin failed to load, why the world took so long — have already rolled out of it. logs/latest.log has the whole history of the current boot; older boots are gzipped in logs/ as <date>-<n>.log.gz (this tool cannot decompress those). If a question is about what happened at startup, read the log file — do not answer from the console buffer and do not assume the buffer is complete.

Other good uses: plugin configuration (plugins/Geyser-Spigot/config.yml), server.properties, eula.txt, crash reports in crash-reports/.

Size guard: the tool first checks the size in the directory listing and REFUSES to fetch anything larger than max_bytes (default from PTERODACTYL_MAX_READ_BYTES, hard cap 4 MiB, which is the panel's own limit). It never partially downloads a huge file. head_lines / tail_lines trim AFTER the download, so they do not help you get past the size guard — the panel has no range-read endpoint.

Binary files (jars, region files, images) are not readable this way; use ptero_list_files to inspect them by size and date instead.

Write a text file on the game server. The body you pass REPLACES the file entirely — this is not an append and not a patch. There is no partial write.

ALWAYS call ptero_read_file on the same path first and build the new content from what is actually there. Writing a config from memory silently drops every setting you did not happen to include.

Creating a NEW file runs immediately. OVERWRITING an existing file is treated as destructive: the first call returns status "needs_confirmation" with a preview (path, current size, new size) and a confirmation_token, and an automatic backup is taken before the write actually happens. Show that preview to the human and only call again with the token once they have agreed.

Protected paths (PTERODACTYL_PROTECTED_PATHS — by default the world directories, server.properties, ops.json, whitelist.json and banned-*.json) are refused outright.

The file content itself is never written to the audit log; only its sha256 and length are.

Upload a file from the machine running this MCP server to the game server, BYTE FOR BYTE. This is the tool for binaries — plugin jars, zips, datapack archives, images, region files — anything ptero_write_file cannot carry because that tool is text-only and would corrupt non-UTF-8 bytes.

You pass a PATH, not content: local_path must be an absolute path to a file that already exists on the machine this server runs on, and the server reads the bytes itself. There is no way to hand it base64 or any other inline payload, so if the file only exists in this conversation, write it to local disk first and pass that path.

It uploads exactly one file and does not unpack anything: a .zip or .tar.gz arrives as an archive, still compressed. There is no decompress tool here.

Creating a NEW remote file runs immediately. OVERWRITING an existing one is destructive: the first call returns status "needs_confirmation" with a preview (remote path, current size, new size) and a confirmation_token, and an automatic backup is taken before the upload happens. Show that preview to the human and only call again with the token once they have agreed. Protected paths (PTERODACTYL_PROTECTED_PATHS) are refused outright, and files larger than 64 MiB are refused before anything is read or sent.

VERIFY AFTERWARDS. The panel hands out a short-lived signed URL and the node answers the upload with an empty 200 — that confirms receipt and nothing more. It does not tell you the file landed at the size you sent, and it never tells you whether the server will accept it. Call ptero_list_files on remote_dir and check the size against the bytes this tool reports. A new plugin jar also needs a server restart before it loads.

The file content is never written to the audit log — only its sha256 and length — and neither is the signed upload URL.

Rename a file or directory — and, because from and to are both interpreted relative to root, MOVE it between directories too. root="/", from="plugins/old.jar", to="plugins/disabled/old.jar" moves the jar into the disabled folder. The destination directory must already exist.

This is the safe way to take a plugin or config out of service: rename it rather than deleting it, and it can be renamed back. Prefer this over ptero_delete_file whenever the change might need undoing.

Both the source and the destination are checked against PTERODACTYL_PROTECTED_PATHS, so a rename cannot be used to move something out of a protected directory. No backup is taken (nothing is destroyed) and no confirmation is required, but the call is counted against PTERODACTYL_MAX_MUTATIONS and audited.

It does not create directories and it does not overwrite: if to already exists the panel returns an error.

Duplicate a file or directory in place. THE PANEL CHOOSES THE NAME OF THE COPY — you cannot specify it. Copying config.yml produces something like config copy.yml (and config copy 2.yml the next time) in the same directory. If you need a specific name, copy first and then ptero_rename_file the result; call ptero_list_files afterwards to find out what the copy was actually called.

The obvious use is a hand-rolled safety net before editing a config: copy it, then ptero_write_file the original. For anything bigger than a single file, a real backup (ptero_create_backup) is better — it is off-server and restorable.

The source path is checked against PTERODACTYL_PROTECTED_PATHS. No confirmation and no automatic backup (nothing is overwritten), but the call is counted against PTERODACTYL_MAX_MUTATIONS and audited. Note the copy consumes disk quota.

Permanently delete one or more files or directories. THIS IS IRREVERSIBLE WITHOUT A BACKUP — the panel has no trash and no undo. Deleting a directory deletes everything under it. Prefer ptero_rename_file (rename it out of the way) whenever the change might need undoing.

Every guardrail applies:

• Deletion is OFF unless the operator set PTERODACTYL_ALLOW_DELETE=true; otherwise every call is refused.

• Paths matching PTERODACTYL_PROTECTED_PATHS are refused — by default the world directories, server.properties, ops.json, whitelist.json and banned-*.json.

• More than 10 files in one call is refused; narrow the list and work in batches.

• An automatic backup is taken before the delete, and the operation is aborted if the backup fails.

The first call does NOT delete anything. It returns status "needs_confirmation" with a preview listing the root, the exact files and the count, plus a single-use token that expires in 120 seconds. THAT PREVIEW IS FOR THE HUMAN: put it in your reply, let them read the list, and only call again with the confirmation_token once they have said yes. Do not round-trip the token automatically — the whole point is that a person sees what is about to be destroyed.

Use dry_run=true if you only want to check what a delete would resolve to.

Send a power signal to the server. start boots it from offline. stop gracefully shuts it down, saving the world first, and disconnects any connected players. restart stops then starts it again, briefly disconnecting players. kill forcibly terminates the process immediately, without saving.

kill is a hard stop and risks world corruption: prefer stop in almost every case, and reach for kill only when the server is hung and unresponsive to a normal stop. kill additionally refuses to run unless PTERODACTYL_ALLOW_KILL=true is set, and when it does proceed an automatic backup is taken first (the kill is aborted if that backup fails).

stop, restart and kill are destructive and require explicit human confirmation before they run — via MCP elicitation where the client supports it, otherwise a two-phase confirmation_token. On the first call (no token) nothing changes: you get back a preview of the current state and what the signal will do. THIS PREVIEW IS FOR THE HUMAN — show it in your reply and wait for their decision; do not silently call the tool again with the token yourself. Only call again, with the same arguments plus confirmation_token, once the human has approved it. start needs no confirmation.

Power actions are rate-limited to one per 30 seconds regardless of signal, to stop restart loops — a second power call inside that window is refused, naming how long to wait.

Set wait_seconds (0-60, default 0) to poll the live power state every 2 seconds after the signal is dispatched and report it back as state_after, instead of returning immediately with only the signal that was sent.

List a server's backups: uuid, name, size, whether each one completed successfully, whether it is locked against deletion, and its created/completed timestamps.

Use this to find a rollback point before or after a risky change, or to check whether a backup started with ptero_create_backup wait:false has finished yet (completed_at is null until it has). Call ptero_create_backup BEFORE any risky file write, delete, or power kill — this tool only reports what already exists, it does not take one for you.

Take a backup of the server right now. Safe. The natural thing to do BEFORE any file write, delete, or power kill — it gives you a rollback point.

By default (wait: true) this blocks until the panel reports the backup complete (polling for up to two minutes) and returns its final size and success state. Pass wait: false to return immediately with just the uuid if you do not want to block; check completion later with ptero_list_backups.

The panel enforces a per-server backup-count limit; creation fails with an actionable error when the server is full — the fix is ptero_delete_backup on an old one, not a retry.

Permanently delete one backup. IRREVERSIBLE — there is no undo and no confirmation from the panel beyond this tool.

Requires PTERODACTYL_ALLOW_DELETE=true. Requires confirmation: the first call without confirmation_token returns a preview (name, size, created_at) and a token instead of deleting anything — THAT PREVIEW IS FOR THE HUMAN, show it and wait for approval before calling again with the token. A locked backup cannot be deleted here at all; unlock it in the panel first.

Get a signed, short-lived URL for downloading one backup archive directly from storage.

Use this when the human wants to pull a backup down outside the panel. The URL grants access to the archive to whoever holds it, expires quickly, and is never written to the audit log — treat it as a bearer credential: do not store it, paste it into a chat log you will keep, or reuse it after it expires (request a fresh one instead).

List a server's scheduled tasks (the panel's Schedules feature): cron timing, whether each is active or currently running, whether it only fires while the server is online, last/next run time, and the ordered tasks each run executes (command/power/backup, with their payload and delay).

Use this to find out what automation is already configured — e.g. a nightly restart or an automatic backup — before assuming a state change was manual, or before adding a new schedule by hand through the panel to avoid a clash.

This is read-only: creating, editing, or deleting schedules is not exposed by this server. Use the panel UI for that.

List the network allocations (ip:port pairs) assigned to this server, and which one is the default/primary.

Use this to find out which port a particular service is meant to use — for example, which port Geyser/Bedrock should bind to — before checking whether it actually bound, which you confirm separately via the console log or logs/latest.log (ptero_read_file). A port being allocated here does not mean anything is actually listening on it.

This is read-only: adding, removing, or repointing allocations is not exposed by this server.

Get the resolved startup command, the raw (unsubstituted) command template, the Docker image, and every user-viewable egg variable — name, env-var name, description, current and default values, whether it's editable, and its validation rule string.

Use this to see how the server is configured to start — e.g. which jar file, memory flags, or Geyser toggle are set — before troubleshooting a boot failure or explaining current configuration.

Hidden (non-user-viewable) variables are never returned by the panel and so never appear here. This tool is read-only: it cannot change a variable, and this server does not currently expose a tool that does — that has to be done through the panel UI.