pterodactyl-mcp

Read the Pterodactyl live console

ptero_get_console_log

Read-onlyIdempotent

Fetch recent console output from a Pterodactyl server via its live websocket. Retrieve the backlog plus new lines, with optional filtering, to monitor or verify command effects.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`filter`	No	Optional case-insensitive filter applied to lines AFTER they are collected: a regular expression if `filter` parses as one, otherwise a plain substring match. Useful for pulling out e.g. Geyser lines ("geyser") from a busy console without widening the window.
`server`	No	Server short identifier (e.g. 1a2b3c4d). Omit to use PTERODACTYL_DEFAULT_SERVER. Call ptero_list_servers to discover valid identifiers.
`max_lines`	No	Stop collecting once this many lines have been gathered (1-1000, default 400). The node's backlog alone is ~150 lines, so the default leaves room to also observe lines streamed during `window_seconds`. `truncated: true` in the result means this cap cut collection short.
`window_seconds`	No	How long to stay connected collecting console output, in seconds (1-60, default 5). Collection stops early once `max_lines` is reached.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Caveats worth surfacing: the server was offline, the node throttled a request, or the filter matched nothing.
`lines`	Yes	Collected console lines, ANSI escape codes stripped, oldest first. Filtered by `filter` when one was given.
`state`	Yes	Wings-reported power state at the time of collection (offline/starting/running/stopping), or "unknown" if no status event arrived during the window.
`server`	Yes	Server short identifier the log was read from.
`truncated`	Yes	True when `max_lines` cut off further backlog or streamed output.
`line_count`	Yes	Number of lines in `lines` (after filtering).
`duration_ms`	Yes	Wall-clock time the collection took, in milliseconds.
`window_seconds`	Yes	The collection window that was actually used.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Sep 26, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it read-only, idempotent, and non-destructive, but the description adds crucial behavioral context beyond that: the websocket round trip is the *only* way to read console output, the buffer rolls over (~1 hour), and collection behavior is governed by `max_lines` and `window_seconds`. It also discloses the `truncated` flag. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: it opens with the core function, then explains why this is the only path, then the alternative, then the mandatory follow-up usage, and finally the filter. Every sentence adds unique value, and there is no fluff or repetition. It's long but appropriately so for a tool with non-obvious websocket behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with websocket collection, streaming, filtering, and truncation, the description covers everything an agent needs: the mechanism, the buffer limitation, the alternative for historical logs, the requirement after sending commands, and the filter semantics. Since an output schema exists, return values don't need description. No relevant gap remains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already documents each parameter, including the filter's regex-vs-substring behavior. The description adds only minor elaboration (e.g., 'without needing a wider window') that largely repeats the schema. Since the schema carries the heavy lifting, a baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description precisely states the verb and resource: 'Connect to the server's live console websocket and return the backlog... plus whatever new lines stream in.' It explicitly distinguishes this from the log-file tool `ptero_read_file` and even from `ptero_send_console_command`, so an agent can instantly tell what this tool does and what it doesn't.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use and when-not-to-use guidance: it names `ptero_read_file` as the alternative for boot-time/plugin-load output and states 'you MUST call this tool to see what the command did' after `ptero_send_console_command`. This is unambiguous routing to the correct tool in each scenario.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.