Pterodactyl MCP Extended
by pawfox
README.md
# pterodactyl-mcp-extended
A fork of [@zefarie/pterodactyl-mcp](https://www.npmjs.com/package/@zefarie/pterodactyl-mcp) 0.1.0 (MIT) that keeps all 73 upstream tools and adds 22 more, most importantly **binary-safe file uploads** (upstream `write_file` sends text, so schematics, jars and other binary files get corrupted).
The upstream bundle in `dist/index.js` is unchanged apart from a 5-line hook; every addition lives in [`extensions/extra-tools.js`](extensions/extra-tools.js).
## Added tools
| Tool | What it does |
|---|---|
| `upload_file` | Upload local files to a server directory via the panel's signed upload URL. Binary-safe, verifies sizes, won't overwrite unless `overwrite: true`, optional `remote_name`. |
| `upload_file_base64` | Same, from base64 bytes (for clients without local file access). |
| `download_file_to_local` | Save a server file to a local path (binary-safe). |
| `pull_file` | Have the node download a URL straight into a server folder. |
| `copy_file` | Duplicate a file in place. |
| `chmod_files` | Change file permissions. |
| `make_directories` | `mkdir -p` for server paths. |
| `execute_schedule` | Run a schedule now. |
| `get_backup` / `toggle_backup_lock` | Backup details; lock or unlock a backup. |
| `list_server_allocations` / `add_server_allocation` / `update_allocation_notes` / `set_primary_allocation` / `remove_server_allocation` | Manage a server's ports from the Client API. |
| `update_startup_variable` | Change a startup variable (e.g. `SERVER_JARFILE`). |
| `rename_server` / `set_docker_image` / `reinstall_server_client` | Server settings via the Client API. |
| `list_client_servers` | Servers the client key can see, with name filter and `type: admin-all`. |
| `find_servers` | Admin search by name/uuid/external_id/image instead of paging `list_servers`. |
| `list_locations` | Admin: node locations. |
## Run it locally
```bash
npm install --omit=dev
```
Claude Desktop entry (`~/.config/Claude/claude_desktop_config.json`):
```json
"my-panel": {
"command": "/usr/bin/node",
"args": ["/absolute/path/to/pterodactyl-mcp/dist/index.js"],
"env": {
"PTERODACTYL_URL": "https://panel.example.com",
"PTERODACTYL_APP_KEY": "ptla_...",
"PTERODACTYL_CLIENT_KEY": "ptlc_..."
}
}
```
## Smoke test
```bash
node test/smoke.mjs --config ~/.config/Claude/claude_desktop_config.json --server my-panel \
--call find_servers '{"query":"lobby"}'
```
Starts the server over stdio with that entry's env (keys are never printed), lists tools and calls each `--call`.
---
## Upstream README
[](https://www.npmjs.com/package/@zefarie/pterodactyl-mcp)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
**The first MCP server for Pterodactyl Panel. Manage your game servers with AI.**
An MCP (Model Context Protocol) server that exposes the Pterodactyl Panel API to LLMs. Connect Claude, Cursor, or any MCP-compatible client to your game server infrastructure and manage it through natural language.
## Features
- **42 MCP tools** covering server management, power control, file management, backups, users, nodes, and more
- **Dual API key support** - Application API (admin) + Client API (power, files, console)
- **Read-only and destructive actions properly annotated** so your AI client can warn before dangerous operations
- **Rate limiting and retry logic built-in** with exponential backoff
- **TypeScript, fully typed** with strict mode enabled
- **Zod validation on all inputs** for robust parameter checking
- **Structured JSON responses** optimized for LLM consumption
- **Health check on startup** to verify panel connectivity
## Quick Start
```bash
npx @zefarie/pterodactyl-mcp
```
## Configuration
Set these environment variables:
| Variable | Required | Description |
|----------|----------|-------------|
| `PTERODACTYL_URL` | Yes | Your Pterodactyl Panel URL |
| `PTERODACTYL_APP_KEY` | Yes | Application API key (starts with `ptla_`) |
| `PTERODACTYL_CLIENT_KEY` | No | Client API key (starts with `ptlc_`) for power/files/console tools |
## Usage with Claude Desktop / Claude Code / Cursor
Add to your MCP configuration:
```json
{
"mcpServers": {
"pterodactyl": {
"command": "npx",
"args": ["-y", "@zefarie/pterodactyl-mcp"],
"env": {
"PTERODACTYL_URL": "https://panel.example.com",
"PTERODACTYL_APP_KEY": "ptla_xxxxxxxxxxxxx",
"PTERODACTYL_CLIENT_KEY": "ptlc_xxxxxxxxxxxxx"
}
}
}
}
```
See [docs/SETUP.md](docs/SETUP.md) for platform-specific config file locations and troubleshooting.
### Hosted Mode (Cloudflare Worker)
You can also deploy pterodactyl-mcp as a Cloudflare Worker, giving each user a unique MCP endpoint URL without running anything locally. See the [Cloudflare Worker Deployment](docs/SETUP.md#cloudflare-worker-deployment) section in the setup guide.
## Available Tools (42)
### Server Management (Application API)
| Tool | Description | Type |
|------|-------------|------|
| `list_servers` | List all servers with ID, identifier, name, status, and limits | Read-only |
| `get_server` | Get detailed server config (limits, egg, container, allocations) | Read-only |
| `create_server` | Create a new server with egg, resources, and allocation | Destructive |
| `delete_server` | Permanently delete a server and all its data | Destructive |
| `update_server_details` | Update server name, description, owner, or external ID | Destructive |
| `update_server_build` | Update resource limits (memory, CPU, disk, swap) | Destructive |
| `update_server_startup` | Update startup command, Docker image, or egg | Destructive |
| `suspend_server` | Suspend a server (prevents users from starting it) | Destructive |
| `unsuspend_server` | Unsuspend a previously suspended server | Destructive |
| `reinstall_server` | Reinstall server egg (wipes all files) | Destructive |
| `list_server_databases` | List databases attached to a server (admin view) | Read-only |
### Power Control (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `start_server` | Start a stopped server | Destructive |
| `stop_server` | Stop a running server gracefully | Destructive |
| `restart_server` | Restart a server (works running or stopped) | Destructive |
| `kill_server` | Forcefully kill a server process (data loss risk) | Destructive |
| `get_server_resources` | Get real-time CPU, memory, disk, network usage and power state | Read-only |
### Console (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `send_command` | Send a console command to a running server | Destructive |
### File Management (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `list_files` | List files and directories in a server's filesystem | Read-only |
| `read_file` | Read the contents of a text file | Read-only |
| `write_file` | Write content to a file (create or overwrite) | Destructive |
| `create_folder` | Create a new directory | Destructive |
| `delete_files` | Delete one or more files or folders | Destructive |
| `rename_file` | Rename or move a file/folder | Destructive |
| `compress_files` | Compress files into a .tar.gz archive | Destructive |
| `decompress_file` | Extract an archive file | Destructive |
### Backups (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `list_backups` | List all backups for a server | Read-only |
| `create_backup` | Create a new server backup | Destructive |
### Startup & Config (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `get_startup_variables` | Get startup command, env variables, and Docker images | Read-only |
### Schedules (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `list_schedules` | List all scheduled tasks (cron jobs) for a server | Read-only |
### Databases (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `list_client_databases` | List databases for a server (client view) | Read-only |
### Sub-users (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `list_subusers` | List sub-users with permissions for a server | Read-only |
### Account (Client API)
| Tool | Description | Type |
|------|-------------|------|
| `get_account` | Get the current authenticated user's account info | Read-only |
### Users (Application API)
| Tool | Description | Type |
|------|-------------|------|
| `list_users` | List all user accounts on the panel | Read-only |
| `get_user` | Get detailed info for a specific user | Read-only |
| `create_user` | Create a new user account | Destructive |
| `update_user` | Update a user's details | Destructive |
### Nodes (Application API)
| Tool | Description | Type |
|------|-------------|------|
| `list_nodes` | List all infrastructure nodes | Read-only |
| `get_node` | Get detailed info for a specific node | Read-only |
| `get_node_config` | Get Wings daemon configuration for a node | Read-only |
### Panel Config (Application API)
| Tool | Description | Type |
|------|-------------|------|
| `list_eggs` | List all available server templates (eggs) | Read-only |
| `list_mounts` | List all mount points | Read-only |
| `list_roles` | List all admin roles | Read-only |
See [docs/TOOLS.md](docs/TOOLS.md) for detailed documentation on each tool, including parameters and example responses.
## Important: Server ID vs Identifier
Pterodactyl uses two different identifiers for servers:
- **`server_id`** (number) - Used by Application API (admin) tools. Example: `7`
- **`server_identifier`** (string) - Used by Client API tools (power, files, console). Example: `"a1b2c3d4"`
Call `list_servers` first to get both values. The response includes both `id` (numeric) and `identifier` (string) for each server.
## Getting API Keys
**Application API Key** (required, `ptla_`):
Admin Panel > Application API > Create New
**Client API Key** (optional, `ptlc_`):
Account > API Credentials > Create
See [docs/SETUP.md](docs/SETUP.md) for detailed instructions.
## Development
```bash
pnpm install # Install dependencies
pnpm build # Build the project
pnpm test # Run unit tests
pnpm lint # Run linter and formatter
pnpm typecheck # Type checking
```
## Contributing
Contributions are welcome! Please make sure `pnpm lint`, `pnpm typecheck`, and `pnpm test` all pass before submitting.
## License
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues