使用说明

翼手指MCP

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

快速安装

选择与您的客户匹配的路径。

uvx（推荐，无需结账）：

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

克劳德桌面一键式（DXT）： 看见构建DXT包在......下面

史密斯利： 即用型 smithery.yaml 在回购根目录下发货。

能力

种类	计数	亮点
工具	50	所有应用程序API路由（用户、服务器、节点、位置、嵌套/蛋、数据库）加上AI友好的助手和通用的原始请求转义填充。
提示	2	`troubleshoot_server`, `provision_user_and_server`
资源	2	`pterodactyl://panel/overview`, `pterodactyl://servers/{server_id}/summary`

这提供了什么

映射到翼手龙的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_...).

面板中的典型流量：

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

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

设置

创建虚拟环境（推荐）：

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

安装依赖项：

pip install -r requirements.txt

配置环境变量：

复制 .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 发现。

Claude Desktop示例（uvx——适用于Windows/macOS/Linux）

编辑您的 claude_desktop_config.json 并添加：

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

Claude Desktop（来自本地结账，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"
      }
    }
  }
}

构建DXT包

该回购提供 manifest.json 所以你可以一键构建 .dxt 对于Claude Desktop：

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

结果 .dxt 文件可以放到Claude Desktop中，它会提示用户 PANEL_URL 和 PANEL_TOKEN 安装时。

发展

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

许可证

麻省理工学院

工具命名

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

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"}

工作流程示例：

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

呼叫 ptero_ai_search_users 随着 query="pixel flip"

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

呼叫 ptero_app_get_users_user 随着 user=<id>

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

ptero_app_list_endpoints