VPN Bypass

Name: VPN Bypass
Author: GeiserX

本地服务

geiserx.github.io安全11 天前更新

代码仓库访问官网

关于 VPN Bypass

vpn-bypass-mcp 将 AI Agent 连接到 macOS 应用 VPN Bypass，以读取和调整流量路由。工具涵盖应用状态、域名与服务规则、路由、DNS 和日志，并支持只读模式。

主要功能

01读取应用状态和日志
02管理域名列表与服务
03更改路由模式和规则
04查看并刷新内核路由
05可选的只读工具集

适用场景

01检查 VPN Bypass 路由状态
02添加绕过 VPN 路由的域名
03通过查看日志排查连接问题

MCP 相关

该 MCP 服务通过本地控制套接字提供控制 VPN Bypass 的工具和提示词。它使用 stdio，不开放网络端口；只读模式仅注册不会修改状态的工具。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "geiserx-vpn-bypass": {
      "command": "npx",
      "args": [
        "-y",
        "vpn-bypass-mcp"
      ],
      "env": {
        "VPNB_SOCKET": "<VPNB_SOCKET>",
        "VPN_BYPASS_MCP_READ_ONLY": "<VPN_BYPASS_MCP_READ_ONLY>"
      }
    }
  }
}

启动命令npx -y vpn-bypass-mcp

需要配置的环境变量

VPNB_SOCKETPath of the VPN Bypass control socket (default ~/Library/Application Support/VPNBypass/control.sock)

VPN_BYPASS_MCP_READ_ONLYSet to 1 to register only the 8 read tools and the diagnose_site prompt; any value except empty, 0, false or no turns it on

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmvpn-bypass-mcp0.2.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

vpn-bypass-mcp

vpn-bypass-mcp 是 VPN Bypass 的 MCP 服务。VPN Bypass 是一款 macOS 菜单栏应用，可决定哪些流量通过 VPN，哪些流量绕过 VPN。AI Agent 可通过应用的本地控制套接字读取应用状态并更改路由。该服务仅在 macOS 上运行。

连接到 vpn-bypass-mcp 的 MCP Inspector：工具列表中选中了 set_mode，并显示其描述和接受的三种模式

功能

23 个工具，每个应用操作对应一个：状态、域名列表、服务、路由模式、内核路由、DNS 刷新、日志，以及 Custom 模式的路由和规则。每个工具都有显示标题。
每个工具都以文本和 structuredContent 的形式原样返回应用自身的 JSON；8 个读取工具还会声明 outputSchema。
每个工具都具备全部 4 种 MCP 提示。每个会改变流量去向的工具都设置了 destructiveHint: true，并包含新增项，因此当客户端会确认破坏性调用时，如果有人注入“将此路由通过我的代理”，客户端会先征求你的确认；custom_add_route 和 custom_update_route 还设置了 openWorldHint: true。
如果应用已经处于所请求的模式，set_mode 不会发送任何内容。
工具未声明的参数会被拒绝，因此拼写错误绝不会在什么都没改变的情况下“成功”。
3 个提示词：diagnose_site、bypass_site、rotate_proxy_port。
VPN_BYPASS_MCP_READ_ONLY=1 只会注册 8 个不会更改任何内容的工具，以及 diagnose_site 提示词。
代理密码通过单独的字段传输，绝不会被返回、回显或记录到日志中。错误会将套接字称为 control.sock，绝不会显示你的主目录。
仅使用 stdio；该服务不会打开网络端口。

协议

MCP 2026-07-28（server/discover、每个请求的 _meta、列表上的缓存提示），以及从同一个二进制文件支持的所有更早版本，最低至 2024-11-05（initialize 握手）。两个时期的客户端均可使用，包括现在仍在使用 initialize 的客户端。

安装

VPN Bypass 必须处于打开状态。npm 包会在安装时为你的 Mac 下载发布版二进制文件；如果包管理器跳过安装脚本（npm 12、pnpm、bun），则会在首次启动时下载，并使用包内附带的哈希值进行校验。

Claude Code：

claude mcp add --transport stdio vpn-bypass -- npx -y vpn-bypass-mcp

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）和 Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "vpn-bypass": {
      "command": "npx",
      "args": ["-y", "vpn-bypass-mcp"]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "vpn-bypass": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vpn-bypass-mcp"]
    }
  }
}

Codex（~/.codex/config.toml）：

[mcp_servers.vpn-bypass]
command = "npx"
args = ["-y", "vpn-bypass-mcp"]

只读模式：在服务的环境中添加 VPN_BYPASS_MCP_READ_ONLY=1（在 JSON 中使用 "env": {"VPN_BYPASS_MCP_READ_ONLY": "1"}，在 Codex 中使用 env = { VPN_BYPASS_MCP_READ_ONLY = "1" }，在 claude mcp add 中将 -e VPN_BYPASS_MCP_READ_ONLY=1 放在名称前）。发布版二进制文件和从源代码构建的说明见入门指南。

工具

分组	工具	只读
状态和日志	`status`、`get_logs`	是
模式	`set_mode`
域名列表	`list_domains`（读取）、`add_domain`、`remove_domain`、`set_domain_enabled`
服务	`list_services`、`get_service`（读取）、`set_service_enabled`
内核路由	`list_active_routes`（读取）、`clear_routes`、`refresh_routes`、`refresh_dns`
自定义模式路由	`custom_list_routes`（读取）、`custom_add_route`、`custom_update_route`、`custom_set_route_enabled`、`custom_remove_route`
自定义模式规则	`custom_list_rules`（读取）、`custom_add_rule`、`custom_remove_rule`、`custom_set_default_route`