Portveil

io.github.roybogs由 GitHub 账号 roybogs 发布v0.4.4更新于 Oct 26, 2026

MCP server for Portveil: let AI assistants see your devices and move them between VPN locations.

已验证STDIO仅桌面云端与基础设施安全与监控

概览

AI 生成的概览

Portveil 的 MCP 服务器，让 AI 助手查看账户中的设备并在不同 VPN 位置之间移动它们。

可以做什么
列出并查看设备、可用位置、账户套餐和近期活动，包括每台设备的实时速度和保护状态。将设备移动到某个国家或城市，或让它轮换到下一个位置。启动和停止定时轮换，按设定的分钟间隔自动移动设备，可限定在选定位置之间。重新连接或断开设备的隧道。添加、重命名、更新或移除设备，手机和笔记本的隧道文件保存在本地。
适用场景
当你管理多台受 Portveil 保护的设备或代理机器，想通过助手切换 VPN 出口位置、按计划轮换位置，或查看哪些设备当前未受保护时，适合使用。
运行要求
通过 npx 在本地运行（需要 Node.js）。需要 Portveil 账户，PORTVEIL_ACCOUNT_ID 中填写账户 ID，PORTVEIL_TOKEN 中填写具有 read 或 control 权限的 API 令牌。PORTVEIL_API 可覆盖 API 基础地址。设备需运行 Portveil 应用或代理并开启远程控制才能被移动。
安装前请注意
PORTVEIL_TOKEN 中的令牌可访问你的账户；请使用限定权限的令牌而非账户密钥，必要时在仪表盘中撤销。control 权限的工具会移动、重连、断开、添加和移除设备，其中断开和移除被标记为破坏性操作。定时轮换会持续切换位置，直到停止。服务器只向 Portveil API 发送请求。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Portveil，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

Portveil MCP server

Let an AI assistant see the devices on your Portveil account and move them between VPN locations.

"Move my scraper box to Finland." "Rotate every agent to a new location." "Which of my devices aren't protected right now?" "Rotate the scraper between the US and Finland every 15 minutes."

Moves are verified: a tool only reports success after the device has switched and the exit server in the new location confirms it sees that device.

Tools

ToolWhat it doesNeeds
list_devicesEvery device: protected or not, where it exits, live speed (↓/↑ Mbps), remote control on/offread
list_locationsThe locations you can move toread
get_deviceOne device's current state, including live speed and any rotationread
get_accountPlan and devices usedread
list_activityRecent moves, reconnects and changes, and which token made themread
move_deviceMove a device to a country or city ("Finland", "US", "Helsinki")control
rotate_deviceMove a device once to the next locationcontrol
start_rotationMove a device automatically every N minutes (5–10080), optionally among chosen locations. Portveil runs the schedule, so the assistant can closecontrol
stop_rotationTurn scheduled rotation offcontrol
reconnect_deviceRe-establish a device's tunnelcontrol
disconnect_deviceTurn a device's VPN off (flagged destructive: a hint that tells well-behaved assistants to check with you first)control
add_deviceAdd a device. Phones and laptops (WireGuard app): creates it and saves its tunnel files locally, key never shown in chat. Linux servers and agent machines: gives the exact commands to run on that machine, which makes its own key and registers itselfadmin (phones/laptops)
update_deviceRename a device and/or turn its remote control on or offadmin
remove_deviceRemove a device for good (flagged destructive)admin

Tool names changed in 0.3.0 to one verb_noun pattern: device_status → get_device, account_info → get_account, recent_activity → list_activity, set_rotation → start_rotation.

Devices can be named loosely ("scraper" finds "Scraper box"); an ambiguous name returns the choices instead of guessing.

Setup

No account yet? Start free with just an email, no card.

  1. In the Portveil dashboard, create an API token. Choose control scope to let the assistant move devices, or read to let it only look. Don't give it your account key.
  2. Note your account ID (acct_…).
  3. Add the server to your assistant:

Claude Code

bash
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) and most other clients:

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

Hermes Agent: Hermes only installs npm packages older than 14 days, so install into its own folder and run it with node:

bash
cd ~ && npm install --prefix ~/.hermes/mcp-servers/portveil [email protected]echo 'PORTVEIL_TOKEN=clt_…' >> ~/.hermes/.envhermes 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

For Hermes to use it well (when to act, what to confirm first, how to add devices), also install the Portveil skill from ClawHub:

bash
hermes skills install roybogs/portveil

(Source: skills/portveil/SKILL.md.)

Devices must be running the Portveil app or the Portveil agent with remote control on. Devices using the plain WireGuard app are shown but can't be moved.

Security

  • Use a scoped API token. Every action it takes is recorded in your account's activity log with the token that made it, and you can revoke it in the dashboard at any time.
  • The server talks only to https://api.portveil.com (override with PORTVEIL_API). It stores nothing.

Development

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

来源：README.md，提交 34328e5

工具

0
SourceWeft 曾在隔离沙箱中以无凭据方式启动该软件包一次，以列出其工具，但未能完成：服务器未能启动。

版本历史

7
  1. v0.4.4最新Oct 26, 2026
  2. v0.4.3Sep 27, 2026
  3. v0.4.2Sep 27, 2026
  4. v0.4.1Sep 26, 2026
  5. v0.3.0Sep 26, 2026
  6. v0.2.0Sep 25, 2026
  7. v0.1.1Sep 25, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分