Content
# PterodactylMCP
[](https://lobehub.com/mcp/pixlflip-enterprises-pterodactylmcp)
[](LICENSE)
[](https://www.python.org/downloads/)
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):**
```bash
uvx pterodactyl-mcp
```
**pip:**
```bash
pip install pterodactyl-mcp
pterodactyl-mcp
```
**Docker:**
```bash
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](#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:
```json
{
"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)
```json
{
"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:
```bash
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
```bash
pip install -e ".[dev]"
ruff check .
pytest
```
## License
[MIT](LICENSE)
## 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]": "admin@example.com", "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`
