Pterodactyl MCP

翼手指MCP

模型上下文协议（MCP）服务器 翼板应用API （管理端点），使用FastMCP构建。

这提供了什么

• 映射到翼手龙的MCP工具 应用程序API 路由（用户、服务器、节点、位置、巢/蛋、服务器数据库）。
• 通用 ptero_app_request 调用任何工具 /api/application/... 端点尚未映射。
• AI友好、令牌高效的工具（搜索、紧凑列表、摘要）。

支持的终结点（应用程序API）

此服务器从NETVPX应用程序API文档中为每条路由公开一个MCP工具，包括：

• 用户：列表/获取/创建/更新/删除，查找方式 external_id
• 服务器：列表/获取/创建/删除，查找方式 external_id，更新详细信息/构建/启动，挂起/取消挂起，重新安装
• 节点：list/get/create/update/delete，列出可部署节点，获取配置，管理分配
• 位置：列表/获取/创建/更新/删除
• 巢/蛋：列出巢穴，得到巢穴，列出鸡蛋，得到鸡蛋
• 服务器数据库：list/get/create/delete，重置数据库密码

AI友好工具（推荐）

这些工具旨在保持响应小和“LLM友好”：

• ptero_ai_search_users （在用户名/电子邮件/姓名/外部id/uuid之间进行前N个模糊搜索）
• ptero_ai_search_servers （跨名称/标识符/uid/external_id的前N个模糊搜索）
• ptero_ai_list_users / ptero_ai_list_servers （紧凑、安全的默认设置）
• ptero_ai_get_user_summary / ptero_ai_get_server_summary （紧凑的单一资源视图）
• ptero_ai_panel_totals （计入共同资源）

参考文献

• FastMCP快速入门：https://gofastmcp.com/getting-started/quickstart
• NETVPX Pterodactyl应用程序API文档：https://pterodactyl-api-docs.netvpx.com/docs/api/application
• NETPX身份验证文档：https://pterodactyl-api-docs.netvpx.com/docs/authentication

需求

• Python 3.10+
• 翼手龙 应用程序API 钥匙(ptla_...)具有适当的权限

获取应用程序API密钥

你需要一个 应用 令牌（通常 ptla_...)，不是客户端令牌(ptlc_...).

面板中的典型流量：

1. 使用管理员帐户登录
2. 打开您帐户的API凭据页面
3. 创建一个 应用程序API 键入并复制它

如果您的面板UI不同，请按照下面的身份验证参考链接进行操作。

设置

1. 创建虚拟环境（推荐）：

• Windows（PowerShell）： python -m venv .venv; .\\.venv\\Scripts\\Activate.ps1
• macOS/Linux： python3 -m venv .venv && source .venv/bin/activate

1. 安装依赖项：

pip install -r requirements.txt

1. 配置环境变量：

• 复制 .env.example 到 .env
• 设置：

- PANEL_URL （例如。 https://panel.example.com) - PANEL_TOKEN （你的 应用 API密钥，通常以 ptla_)

可选环境变量：

• PANEL_TIMEOUT （秒，默认值 30)
• PANEL_VERIFY_SSL (true/false，默认值 true)
• PANEL_USER_AGENT （默认值 PterodactylMCP/0.1)

运行MCP服务器

STDIO传输（建议用于桌面MCP客户端）

从repo根目录：

python run_server.py

或者：

python -m pterodactyl_mcp

HTTP传输（可选）

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

从MCP客户端连接

大多数MCP桌面客户端将服务器作为子进程启动。将它们指向：

• 命令： python
• Args： C:\\path\\to\\PterodactylMCP\\run_server.py （推荐）

如果您的客户端不将此仓库作为工作目录运行，请首选设置 PANEL_URL 和 PANEL_TOKEN 在客户端配置环境中，而不是依赖 .env 发现。

克劳德桌面示例（Windows）

编辑 %APPDATA%\\Claude\\claude_desktop_config.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"
      }
    }
  }
}

工具命名

路线工具是使用以下模式生成的：

ptero_app_{method}_{path} （与 /api/application/ 远离的， / → _, - → _, {param} → param).

调用工具

• 每个路由工具都将路由路径参数作为普通参数（例如。 server, user, node)，加上可选 query 和 body.
• 使用 query 用于查询字符串参数（分页、筛选器、包含），以及 body 用于JSON请求有效载荷。
• 要查找所有工具名称及其路线，请致电 ptero_app_list_endpoints.
• 为了提高代币效率，请选择 ptero_ai_* 发现工具（搜索/列表/摘要），然后调用原始 ptero_app_* 一旦你有了确切的ID，就可以使用路由工具。

示例查询参数（括号是有效的字典键）：

• {"filter[email]": "admin@example.com", "include": "servers"}

工作流程示例：

1. 找到你指的用户（紧凑的结果）：

• 呼叫 ptero_ai_search_users 和 query="pixel flip"

1. 然后只获取所选匹配的完整对象：

• 呼叫 ptero_app_get_users_user 和 user=

要列出所有公开的工具及其路线，请致电：

• ptero_app_list_endpoints