What is io.github.GeiserX/vpn-bypass-mcp?

Read and change VPN Bypass (macOS) routing: domain lists, services, modes, kernel routes, logs

How do I install io.github.GeiserX/vpn-bypass-mcp?

Clone io.github.GeiserX/vpn-bypass-mcp from https://github.com/GeiserX/vpn-bypass-mcp and configure it as an MCP server in your client (Claude Desktop, Cursor, or VS Code).

Is io.github.GeiserX/vpn-bypass-mcp open source?

Yes, io.github.GeiserX/vpn-bypass-mcp is open source under the MIT license. Source code is available at https://github.com/GeiserX/vpn-bypass-mcp.

What category does io.github.GeiserX/vpn-bypass-mcp belong to?

io.github.GeiserX/vpn-bypass-mcp is listed under Developer Tools MCP servers on MCPFind.

io.github.GeiserX/vpn-bypass-mcp — MCP Server for Developer Tools

vpn-bypass-mcp is an MCP server for VPN Bypass, the macOS menu bar app that decides which traffic uses the VPN and which goes around it. An AI agent uses it to read the app's state and change its routing through the app's local control socket. It runs on macOS only.

Features

23 tools, one per app action: status, domain lists, services, routing mode, kernel routes, DNS refresh, the log, and Custom-mode routes and rules.
Every tool returns the app's own JSON unchanged, so fields a newer app adds reach the agent.
Tool descriptions tell an agent that has never seen the app what each mode does, and keep kernel routes apart from Custom-mode egress routes.
MCP hints on every tool (readOnlyHint, destructiveHint, idempotentHint), so a client can ask before a destructive call.
VPN_BYPASS_MCP_READ_ONLY=1 registers only the 8 tools that change nothing.
Errors an agent can act on: the app is not running, the app is older than 4.9.0 (with its version when it reports one), or the app's own error code.
A proxy password travels in a separate field and is never returned, echoed or logged.
stdio only; the server opens no network port.

Quick start

npx -y vpn-bypass-mcp --version

Then add the server to your MCP client (Claude Desktop, Cursor, or any client that reads mcpServers):

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

VPN Bypass must be open. The domain, service, active-route, refresh and log tools need VPN Bypass 4.9.0 or newer; status, set_mode and the Custom-mode tools work with older versions. Claude Code, the release binaries and building from source are in Getting started.

Documentation

The full documentation is at geiserx.github.io/vpn-bypass-mcp.

Getting started: requirements, npm, release binary, source, first run
Configuration: environment variables, read-only mode, timeouts, security
Usage: modes, the two kinds of route, every tool, errors
Development: build, test, release
Related projects: the VPN Bypass app, its vpnb command line, and where this server is listed

Related projects

VPN Bypass, the app, and its Homebrew tap.

License

MIT

Set up in your AI client

AI clientOperating system

Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.

json

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

Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.

Claude Desktop setup reference

Compatible MCP Clients

io.github.GeiserX/vpn-bypass-mcp works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.

Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.

Cursor~/.cursor/mcp.jsonRestart Cursor for changes to take effect.

VS Code.vscode/mcp.jsonReload VS Code window for changes to take effect.

Windsurf~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect.

Claude Code.mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.

io.github.GeiserX/vpn-bypass-mcp