Wisp MCP

Wisp MCP — 将 WISP 游戏面板连接到 AI

English · Français

Wisp MCP 是一个可查看源代码的模型上下文协议服务，适用于 WISP 游戏面板客户端 API。它让兼容 MCP 的 AI 客户端通过面板检查和管理游戏服务，而不是赋予 AI 对主机的无限制访问权限。

它不依赖特定托管服务提供商。只要您的托管服务商提供 WISP 面板和客户端 API 令牌，就可以使用该面板的 URL。无需针对特定服务提供商编写代码。

从可视化指南开始： https://wisp.hinoake.com/en/

我使用的是 WISP 面板吗？

如果您的游戏服务面板看起来像这样，那么它很可能是 WISP：

典型的 WISP 客户端控制面板。托管服务商可以为 WISP 使用白标，因此颜色、徽标和域名可能有所不同。

如果您不确定，请咨询托管服务商：“我的服务器使用的是 WISP 吗？我可以创建 WISP 客户端 API 令牌吗？” 请参阅如何识别 WISP。

功能

• 检查服务器状态、CPU、内存、磁盘和网络使用情况；
• 浏览分页目录、读取配置文件并查看日志尾部；
• 搜索大型文件并读取有范围限制的内容块，避免大量内容涌入模型上下文；
• 创建文件，或通过 SHA-256 变更检测安全编辑现有插件／配置文件；
• 发送控制台命令；
• 启动、停止和重启服务器；
• 创建和检查备份；
• 在启用数据库管理功能时管理数据库；
• 检查审计日志和常见面板状态；
• 通过 stdio 在本地运行，或通过 Streamable HTTP 远程运行；
• 通过单独的功能开关限制破坏性操作。

由于它面向的是 WISP，而不是某一种游戏，因此同一个 MCP 可用于由 WISP 管理的 Rust、Minecraft 和其他游戏服务器。

在 Linux VPS 上安装

适用于 Debian 12 或 Ubuntu 24.04+：

curl -fsSL https://raw.githubusercontent.com/BreezeDelegate/wisp-mcp/main/install-vps.sh | sudo bash

安装程序会询问：

1. 托管服务商提供的 WISP 面板 URL；
2. 可选的默认服务器 ID；
3. 在隐藏的终端提示中输入您的 WISP 客户端 API 令牌。

它会创建专用系统用户，将凭据存储在 Git 仓库之外，并在报告成功前运行 wisp-mcp doctor。

如需进行更深入的只读 API 兼容性检查，请运行 wisp-mcp compatibility。该命令会验证 MCP 使用的最小响应约定，不会修改游戏服务器。

对于 ChatGPT，请同时安装 OpenAI 隧道助手：

curl -fsSL https://raw.githubusercontent.com/BreezeDelegate/wisp-mcp/main/install-vps.sh | sudo bash -s -- --with-openai

连接 AI 客户端

Wisp MCP 不依赖特定模型厂商。它实现了标准 MCP 传输方式。

ChatGPT

对于始终在线的私有 VPS，请使用 OpenAI Secure MCP Tunnel，然后在 ChatGPT Developer Mode 中将 MCP 添加为自定义应用。请参阅 ChatGPT 设置。

Claude Code

Claude Code 可以直接启动 Wisp MCP。如果 Wisp MCP 位于远程 VPS 上，请使用 SSH 作为 stdio 命令：

claude mcp add --scope user wisp -- ssh user@your-vps /usr/local/bin/wisp-mcp-stdio

然后验证：

claude mcp get wisp

其他 MCP 客户端

使用以下任一种标准传输方式：

• stdio：/usr/local/bin/wisp-mcp-stdio，或用于在远程启动该程序的 SSH 命令；
• Streamable HTTP：在身份验证和安全网络边界后运行 wisp-mcp serve；
• MCP Bundle：如果您的客户端支持 Bundle，请从最新版本下载 .mcpb 构件。

请参阅 AI 客户端兼容性。

本地快速开始

要求：Python 3.11+ 和 WISP 客户端 API 令牌。

git clone https://github.com/BreezeDelegate/wisp-mcp.git
cd wisp-mcp
./setup.sh

或者在现有 Python 环境中：

python -m pip install .
wisp-mcp init
wisp-mcp doctor
wisp-mcp

配置

必需值：

WISP_PANEL_URL=https://panel.example.com
WISP_API_TOKEN=your_token

可选的默认服务：

WISP_SERVER_ID=ABCDEFGH

写入功能需选择启用：

WISP_ALLOW_COMMANDS=true
WISP_ALLOW_FILE_WRITES=true
WISP_ALLOW_POWER=true
WISP_ALLOW_BACKUPS=true
WISP_ALLOW_DATABASES=false
WISP_ALLOW_SERVER_SETTINGS=false
WISP_ALLOW_DESTRUCTIVE=false

日常管理期间，请保持 WISP_ALLOW_DESTRUCTIVE=false。删除文件、恢复/删除备份、删除数据库/轮换密码、强制终止进程和更新面板等操作需要单独启用破坏性操作开关。

AI 引导设置

对于初学者，可将以下内容复制到支持 MCP 的助手中：

Help me install Wisp MCP from https://github.com/BreezeDelegate/wisp-mcp. Read the current repository documentation first and reply in my language. First help me confirm that my game host uses the WISP panel. Then guide me one step at a time and do as much of the technical work as possible. Never ask me to paste API tokens, passwords, private keys, or tunnel runtime keys into chat; tell me exactly where to enter secrets directly in the terminal or provider UI. Use the smallest sensible Linux VPS if I need an always-on machine. Verify the WISP connection with wisp-mcp doctor before connecting my AI client. Start read-only, enable only the capabilities I need, keep destructive operations disabled by default, back up before risky changes, and verify status and logs after every change.

请参阅 AI 引导设置 和 VPS 规格选择。

分发与发现

Wisp MCP 已以 io.github.BreezeDelegate/wisp-mcp 的名称发布到官方 MCP Registry。

发行版包括：

• Python wheel；
• 源代码归档；
• .mcpb MCP Bundle。

Registry 发布流程通过使用 OIDC 的签名 GitHub 发行版工作流自动完成。

大文件与安全编辑

对于较大的源文件或日志，可以先使用有范围限制的工具定位相关代码，但不要为了减少内容而舍弃正确性所需的上下文。如果某项更改依赖全局状态、相距较远的钩子、共享类、控制流或文件内的交互，即使会消耗更多 token，也应读取完整文件。

• find_in_file 返回字面匹配项附近的小段内容，并标注行号；
• read_file_chunk 返回有范围限制的字符区间以及 next_offset_chars；
• file_fingerprint 返回 SHA-256、字节数、字符数和行数，不返回文件内容。

常规 read_file 响应也会包含 SHA-256 指纹。对于现有文件，请将该指纹用于：

• safe_write_file，用于有意进行的整文件替换；
• replace_in_file，用于在大文件中进行小范围的精确替换。

这两种受保护的写入工具都会在写入前重新读取文件，并在写入后验证存储的内容。这里使用的是乐观并发控制，而非原子文件系统锁，因为 WISP Client API 无法通过此集成提供比较并交换写入原语。

服务器、目录、备份、数据库和审计日志的列表均支持有范围限制的分页，因此客户端无需一次性加载没有范围限制的集合。

安全模型

工具绝不会返回 API 和 MCP 令牌。未配置身份验证时，远程 HTTP 请求会默认拒绝。文件路径和对象 ID 均经过验证，写入范围受到限制，可变更功能需选择启用。

服务器还会向 MCP 客户端发布操作说明：先检查，再在执行高风险更改前备份，尽量只做最小改动，然后验证状态和日志。

如需私下报告安全问题，请按照 SECURITY.md 中的说明操作。

文档

• 可视化入门指南
• 入门
• 如何识别 WISP 面板
• 连接 ChatGPT、Claude Code 和其他 MCP 客户端
• ChatGPT / OpenAI Secure MCP Tunnel
• VPS 规格选择
• 运维与安全
• AI 引导设置

常见问题

这是否绑定某家托管公司？

不是。此集成面向标准 WISP Client API。请使用运行 WISP 面板的托管服务商提供的面板 URL 和 Client API 令牌。

这是否绑定 Rust 或 Minecraft？

不是。它管理 WISP 所提供的游戏服务器环境，因此同一集成可用于不同游戏。

所有 AI 应用都能使用它吗？

不能。AI 应用必须支持 Model Context Protocol。Wisp MCP 支持标准的 stdio 和 Streamable HTTP 部署模式，因此无需编写特定于供应商的服务端代码，即可兼容常见的 MCP 客户端。

它能修改我的服务器吗？

只有启用了相应功能时才可以。默认情况下为只读，破坏性操作还需要单独启用开关。

许可证

Wisp MCP 根据 PolyForm Noncommercial License 1.0.0 分发。商业许可需另行获得版权所有者的许可。