VPN Bypass

vpn-bypass-mcp

vpn-bypass-mcp は、VPN Bypass 用の MCP サーバーです。VPN Bypass は、どのトラフィックを VPN 経由にし、どのトラフィックを VPN を経由させずに送るかを決める macOS のメニューバーアプリです。AI エージェントはアプリのローカル制御ソケットを通じて、アプリの状態を読み取り、ルーティングを変更できます。macOS 専用です。

機能

• アプリの各アクションに対応する 23 個のツール：ステータス、ドメインリスト、サービス、ルーティングモード、カーネルルート、DNS の更新、ログ、Custom モードのルートとルールです。各ツールには表示用タイトルがあります。
• すべてのツールが、アプリ独自の JSON を変更せずにテキストと structuredContent で返します。読み取りツール 8 個には outputSchema も宣言されています。
• すべてのツールに MCP ヒント 4 種類すべてを設定しています。トラフィックの経路を変更するツールには 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、リストのキャッシュヒント）と、それ以前のすべてのバージョン（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

ドメイン、サービス、アクティブルート、更新、ログの各ツールを使用するには、VPN Bypass 4.9.0 以降が必要です。status、set_mode、カスタムモードの各ツールは、それより古いバージョンでも動作します。各ツールの引数、ヒント、ソケットコマンドについては、使い方をご覧ください。

ドキュメント

すべてのドキュメントはgeiserx.github.io/vpn-bypass-mcpでご覧いただけます。

• はじめに: 要件、npm、リリースバイナリ、ソース、初回実行
• 設定: 環境変数、読み取り専用モード、タイムアウト、セキュリティ
• 使い方: モード、2 種類のルート、各ツール、エラー
• 開発: ビルド、テスト、リリース
• 関連プロジェクト: VPN Bypass アプリ、その vpnb コマンドライン、およびこのサーバーの掲載先

関連プロジェクト

アプリのVPN Bypassと、そのHomebrew tap。

ライセンス

MIT