Portveil

Portveil MCP 服务

让 AI 助手查看你 Portveil 账户中的设备，并在不同 VPN 位置之间移动设备。

“把我的爬虫设备移到芬兰。” “把每个 Agent 都切换到新位置。” “我有哪些设备目前没有受到保护？” “每隔 15 分钟在美国和芬兰之间切换爬虫设备。”

移动操作会经过验证：只有设备已完成切换，并且新位置的出口服务器确认已看到该设备后，工具才会报告成功。

工具

工具	功能	需要的权限
list_devices	列出每台设备：是否受到保护、出口位置、实时速度（↓/↑ Mbps）、远程控制是否开启	读取
list_locations	列出可将设备移至的位置	读取
get_device	查看一台设备的当前状态，包括实时速度和任何轮换设置	读取
get_account	查看套餐和已使用的设备数	读取
list_activity	查看近期移动、重新连接和变更，以及执行操作的令牌	读取
move_device	将设备移至某个国家或城市（“Finland”“US”“Helsinki”）	控制
rotate_device	将设备移动一次，切换到下一个位置	控制
start_rotation	每隔 N 分钟（5–10080）自动移动设备，也可以指定要轮换的位置。计划由 Portveil 执行，因此助手可以关闭	控制
stop_rotation	关闭定时轮换	控制
reconnect_device	重新建立设备的隧道	控制
disconnect_device	关闭设备的 VPN（标记为破坏性操作：这会提示行为得当的助手先征求你的确认）	控制
add_device	添加设备。手机和笔记本电脑（WireGuard 应用）：创建设备并将其隧道文件保存在本地，密钥不会显示在聊天中。Linux 服务器和 Agent 机器：提供需要在该机器上运行的准确命令，由该机器生成自己的密钥并完成注册	管理（手机/笔记本电脑）
update_device	重命名设备，和/或开启或关闭其远程控制	管理
remove_device	永久移除设备（标记为破坏性操作）	管理

在 0.3.0 版本中，工具名称统一改为 verb_noun 模式：device_status → get_device、account_info → get_account、recent_activity → list_activity、set_rotation → start_rotation。

设备名称可以模糊匹配（“scraper”可匹配“Scraper box”）；如果名称不明确，工具会返回候选项，而不是自行猜测。

设置

还没有账户？只需提供电子邮箱，无需银行卡即可免费开始使用。

1. 在 Portveil 控制面板中创建一个 API 令牌。选择 control 权限范围，让助手可以移动设备；选择 read，则助手只能查看信息。不要向它提供你的账户密钥。
2. 记下你的账户 ID（acct_…）。
3. 将服务添加到你的助手：

Claude Code

claude mcp add portveil -e PORTVEIL_ACCOUNT_ID=acct_… -e PORTVEIL_TOKEN=clt_… -- npx -y portveil-mcp

Claude Desktop（claude_desktop_config.json）、Cursor（.cursor/mcp.json）及大多数其他客户端：

{
  "mcpServers": {
    "portveil": {
      "command": "npx",
      "args": ["-y", "portveil-mcp"],
      "env": { "PORTVEIL_ACCOUNT_ID": "acct_…", "PORTVEIL_TOKEN": "clt_…" }
    }
  }
}

Hermes Agent：Hermes 只会安装发布时间超过 14 天的 npm 包，因此请安装到它自己的文件夹中，并使用 node 运行：

cd ~ && npm install --prefix ~/.hermes/mcp-servers/portveil [email protected]
echo 'PORTVEIL_TOKEN=clt_…' >> ~/.hermes/.env
hermes mcp add portveil --command node \
  --env PORTVEIL_ACCOUNT_ID=acct_… 'PORTVEIL_TOKEN=${PORTVEIL_TOKEN}' \
  --args ~/.hermes/mcp-servers/portveil/node_modules/portveil-mcp/dist/index.js

为让 Hermes 更好地使用它（何时执行操作、哪些情况需要先确认、如何添加设备），还请从 ClawHub 安装 Portveil 技能：

hermes skills install roybogs/portveil

（来源：skills/portveil/SKILL.md。）

设备必须运行 Portveil 应用或开启了远程控制的 Portveil Agent。使用纯 WireGuard 应用的设备会显示出来，但无法移动。

安全

• 使用受限权限的 API 令牌。该令牌执行的每项操作都会连同执行操作的令牌一起记录在账户活动日志中；你可以随时在控制面板中撤销该令牌。
• 服务只会与 https://api.portveil.com 通信（可通过 PORTVEIL_API 覆盖）。它不会存储任何内容。

开发

npm install
npm test        # builds, then runs the tests against a fake Portveil API