PterodactylMCP

MCP Badge License: MIT Python 3.10+

Model Context Protocol (MCP) server for the Pterodactyl Panel Application API (admin endpoints), built with FastMCP.

Quick install

Pick whichever path matches your client.

uvx (recommended, no checkout needed):

uvx pterodactyl-mcp

pip:

pip install pterodactyl-mcp
pterodactyl-mcp

Docker:

docker build -t pterodactyl-mcp .
docker run --rm -i \
  -e PANEL_URL=https://panel.example.com \
  -e PANEL_TOKEN=ptla_REPLACE_ME \
  pterodactyl-mcp

Claude Desktop one-click (DXT): see Building a DXT bundle below.

Smithery: a ready-to-use smithery.yaml ships at the repo root.

Capabilities

Kind	Count	Highlights
Tools	50	All Application API routes (users, servers, nodes, locations, nests/eggs, databases) plus AI-friendly helpers and a generic raw-request escape hatch.
Prompts	2	troubleshoot_server, provision_user_and_server
Resources	2	pterodactyl://panel/overview, pterodactyl://servers/{server_id}/summary

What this provides

• MCP tools that map to Pterodactyl Application API routes (users, servers, nodes, locations, nests/eggs, server databases).
• A generic ptero_app_request tool for calling any /api/application/... endpoint not yet mapped.
• AI-friendly, token-efficient tools (search, compact lists, summaries).

Supported endpoints (Application API)

This server exposes one MCP tool per route from the NETVPX Application API docs, including:

• Users: list/get/create/update/delete, lookup by external_id
• Servers: list/get/create/delete, lookup by external_id, update details/build/startup, suspend/unsuspend, reinstall
• Nodes: list/get/create/update/delete, list deployable nodes, get config, manage allocations
• Locations: list/get/create/update/delete
• Nests/Eggs: list nests, get nest, list eggs, get egg
• Server databases: list/get/create/delete, reset database password

AI-friendly tools (recommended)

These tools are designed to keep responses small and “LLM-friendly”:

• ptero_ai_search_users (top-N fuzzy search across username/email/name/external_id/uuid)
• ptero_ai_search_servers (top-N fuzzy search across name/identifier/uuid/external_id)
• ptero_ai_list_users / ptero_ai_list_servers (compact, safe defaults)
• ptero_ai_get_user_summary / ptero_ai_get_server_summary (compact single-resource views)
• ptero_ai_panel_totals (counts for common resources)

References

• FastMCP Quickstart: https://gofastmcp.com/getting-started/quickstart
• NETVPX Pterodactyl Application API docs: https://pterodactyl-api-docs.netvpx.com/docs/api/application
• NETVPX Authentication docs: https://pterodactyl-api-docs.netvpx.com/docs/authentication

Requirements

• Python 3.10+
• A Pterodactyl Application API key (ptla_...) with appropriate permissions

Getting an Application API key

You need an Application token (usually ptla_...), not a Client token (ptlc_...).

Typical flow in the panel:

1. Sign in with an admin account
2. Open your account’s API credentials page
3. Create an Application API key and copy it

If your panel UI differs, follow the Authentication reference link below.

Setup

1. Create a virtual environment (recommended):

• Windows (PowerShell): python -m venv .venv; .\\.venv\\Scripts\\Activate.ps1
• macOS/Linux: python3 -m venv .venv && source .venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

3. Configure environment variables:

• Copy .env.example to .env
• Set:
  • PANEL_URL (e.g. https://panel.example.com)
  • PANEL_TOKEN (your Application API key, usually starts with ptla_)

Optional env vars:

• PANEL_TIMEOUT (seconds, default 30)
• PANEL_VERIFY_SSL (true/false, default true)
• PANEL_USER_AGENT (default PterodactylMCP/0.1)

Run the MCP server

STDIO transport (recommended for desktop MCP clients)

From the repo root:

python run_server.py

Alternatively:

python -m pterodactyl_mcp

HTTP transport (optional)

python -m pterodactyl_mcp --transport sse --host 127.0.0.1 --port 8000 --path /mcp

Connecting from an MCP client

Most MCP desktop clients launch the server as a subprocess. Point them at:

• Command: python
• Args: C:\\path\\to\\PterodactylMCP\\run_server.py (recommended)

If your client does not run with this repo as the working directory, prefer setting PANEL_URL and PANEL_TOKEN in the client config environment instead of relying on .env discovery.

Claude Desktop example (uvx — works on Windows/macOS/Linux)

Edit your claude_desktop_config.json and add:

{
  "mcpServers": {
    "pterodactyl": {
      "command": "uvx",
      "args": ["pterodactyl-mcp"],
      "env": {
        "PANEL_URL": "https://panel.example.com",
        "PANEL_TOKEN": "ptla_REPLACE_ME"
      }
    }
  }
}

Claude Desktop (from a local checkout, Windows)

{
  "mcpServers": {
    "pterodactyl": {
      "command": "python",
      "args": ["C:\\\\path\\\\to\\\\PterodactylMCP\\\\run_server.py"],
      "env": {
        "PANEL_URL": "https://panel.example.com",
        "PANEL_TOKEN": "ptla_REPLACE_ME"
      }
    }
  }
}

Building a DXT bundle

This repo ships a manifest.json so you can build a one-click .dxt for Claude Desktop:

npm install -g @anthropic-ai/dxt
dxt pack

The resulting .dxt file can be dropped into Claude Desktop — it prompts the user for PANEL_URL and PANEL_TOKEN on install.

Development

pip install -e ".[dev]"
ruff check .
pytest

License

MIT

Tool naming

Route tools are generated using the pattern:

ptero_app_{method}_{path} (with /api/application/ removed, / → _, - → _, {param} → param).

Calling tools

• Each route tool takes the route path params as normal arguments (e.g. server, user, node), plus optional query and body.
• Use query for query-string parameters (pagination, filters, includes), and body for JSON request payloads.
• To discover all tool names and their routes, call ptero_app_list_endpoints.
• For token efficiency, prefer the ptero_ai_* tools for discovery (search/list/summary), then call the raw ptero_app_* route tool once you have the exact ID.

Example query params (brackets are valid dict keys):

• {"filter[email]": "[email protected]", "include": "servers"}

Example workflow:

1. Find the user you mean (compact results):

• Call ptero_ai_search_users with query="pixel flip"

2. Then fetch the full object only for the selected match:

• Call ptero_app_get_users_user with user=<id>

To list all exposed tools and their routes, call:

• ptero_app_list_endpoints