Pteropilot · 开源免费 · MIT

Pteropilot 使用教程

三步接上你的面板：安装、配置、提问。

Pteropilot 是 MCP server，让 Claude、Cursor 等 AI 助手用自然语言管理 Pterodactyl / Pelican 面板上的游戏服务器。全程不需要写代码。

第 1 步 · 安装

用 uvx 一条命令

需要 Python 3.12+。项目用 uv 管理，一条命令安装并运行：

$ uvx pteropilot

没有 uv？先装 uv（Windows：pip install uv）。也可以 pip install pteropilot 直接安装。

装过旧版？升级：uvx --refresh pteropilot（或 pip install -U pteropilot）；PyPI 版本可能滞后，最新版可从 GitHub 直装。

第 2 步 · 配置客户端

把 pteropilot 加进你的 AI 客户端

在 Claude Desktop / Cursor 的 MCP 配置里加一段（面板地址和 API Key 也一起填）：

{
  "mcpServers": {
    "pteropilot": {
      "command": "uvx",
      "args": ["pteropilot"],
      "env": {
        "PANEL_URL": "https://你的面板地址",
        "PANEL_API_KEY": "你的面板 API Key",
        "PANEL_READONLY": "0"
      }
    }
  }
}

Claude Desktop：编辑 claude_desktop_config.json；Cursor：MCP 面板里添加。
PANEL_URL 要带协议（https://）；API Key 用权限最小化的那个（见第 4 步）。
改完配置重启客户端，等 AI 识别到 pteropilot 的 39 个工具。
配置完先让 AI 执行 check_panel_connection 自检：返回「✅ 已连通」即配置正确；报 401/403/404 会给出具体排查方向。

第 3 步 · 提问

用自然语言干活

「列出我所有服务器和状态」

「smp 服最近一次备份是什么时候？没有就现在建一个」

「往 creative 服上传这个插件并重启」

「看看最近日志有没有崩溃信号」

「smp 服的 IP 和端口是多少？」

「这个服分配的数据库地址和账号是什么？」

更多能力：电源控制、控制台指令、文件管理、备份、玩家在线、网络地址、数据库信息、批量操作、广播公告、定时重启、崩服告警。完整清单见 pteropilot 项目页。

第 4 步 · 安全建议

先只看，再动手

先设 PANEL_READONLY=1 试用：AI 只能看不能动，确认行为后再开写权限。
给 AI 用权限最小化的 API Key：在面板里创建只含必要权限的 API Key。
危险操作（重启、删文件、覆盖备份）会要求二次确认；写操作走面板 API，Key 不出本机。

第 5 步 · 出问题先看这里

连不上？先自检

配好之后先跑一条命令，它会告诉你哪一步没通——输出不含密钥本身，可以直接贴给别人看。

$ pteropilot --doctor

全部正常时退出码是 0，有问题 1；加 --no-network 只查配置不联网。

常见报错对照表

下面这些是工具本身会打出来的原文，对着表找即可。

现象	原因	怎么办
连不上面板	PANEL_URL 写错——最常见的是漏了 `https://`，或填了带路径的地址	用面板根地址，如 `https://panel.example.com`；`--doctor` 会显示规范化后的地址
401	API Key 无效或已被撤销	检查 `PANEL_API_KEY` 是否复制完整、是否已在面板里删掉
403 · 核心工具	把应用密钥（`ptla_` / `papp_`）当成了 `PANEL_API_KEY`	电源、控制台、文件、备份走客户端 API，请改用客户端密钥（`ptlc_` / `pacc_`）
403 · list_nodes / list_users	没设 `PANEL_APP_KEY`	这几个工具走应用 API，需要另外配应用密钥
404	`PANEL_URL` 或服务器标识不对	常见于地址里带了 `/api`——会自动剥掉后缀；但仍建议填根地址
429	请求过于频繁被限流	等一会儿再试，或减少并发工具调用
响应超时（30 秒）	面板负载过高或网络不稳	稍后重试；面板本身卡住时工具也会一起超时
工具数比文档少	装到了旧版本	`pteropilot --version` 看版本；最新 wheel 在 GitHub Releases

密钥前缀决定它能干什么：ptlc_ / pacc_ 是客户端密钥（管单台服务器），ptla_ / papp_ 是应用密钥（管整个面板）。
面板地址带 /api 会被自动剥掉，但真实子路径（如 /pterodactyl）会保留。

想要图形界面？

试试 Pteropilot Pro

Windows 图形客户端（标准版 + Lite）：面板管理界面、内置 AI 助手、自动备份、云同步与自动更新。7 天全功能试用，上线优惠价 ¥59.99。

了解 Pro → 回到 Pteropilot 项目页