Claude Voice Bridge — macOS and Windows

0.2.0 preview · MIT licensed. Core tests pass on real Mac and Windows runners. Windows interactive desktop actions and Claude Voice routing remain unverified.

Use a remote MCP connector in Claude to reach tools on your own Mac or Windows PC. The bridge provides OAuth authorization and direct local execution. It does not run a second model for direct tools and needs no inference API key.

Why this exists

Claude Desktop can use local stdio MCP servers. A Claude web or mobile conversation needs a reachable remote connector instead. This bridge exposes direct local tools and can start separate clients for MCP servers configured in Claude Desktop. It does not attach to Desktop's conversation or reuse Desktop's active app session.

Voice routing is unverified. This project cannot enable custom connector tools in Claude Voice. Availability depends on Claude's client and your account. Test in text first, then voice. A working OAuth connector does not prove voice support.

Related MCP server: lnwjud

Security and privacy

This is full-machine access, not a sandbox. An authorized client can run shell commands with your logged-in user's authority, read and change files, control apps, use the clipboard, and send messages through installed tools. Natural-language confirmation requests are not enforced authorization boundaries.

• Screen captures are sent to the requesting MCP client and can disclose anything visible: passwords, messages, documents, notifications, and other people's data. Capture images are returned as resized JPEGs. The bridge does not intentionally save them, but the client, model service, or conversation may retain them.

• Shell output, file content, clipboard content, and app data also leave the machine when returned to a remote client. OAuth protects access, not the sensitivity of the returned data. Public Funnel routing exposes the authorization surface.

• macOS permissions granted to shared Python/Node runtimes can affect other scripts.

• Treat the bridge passphrase and OAuth state as credentials. Do not put machine settings, private test evidence, or real connector URLs into this repository.

• UI enable/disable settings change the catalog to reduce accidental use. They do not contain a client that can already run unrestricted shell commands.

Only deploy this for a trusted personal account. Keep the machine updated. Review the risks before exposing it publicly, and stop the service when it is not needed.

Install and connect

Choose the instructions for your OS. The core passes real macOS and Windows CI on Python 3.12 and 3.13. Interactive Windows desktop actions and Claude Voice routing remain unverified. See RELEASE_READINESS.md.

Python 3.12+, uv, and Tailscale with Funnel permission are required on either OS. Start from your checkout:

macOS

uv sync --locked
./mac-bridge.sh install --public-url https://YOUR-HOSTNAME
./mac-bridge.sh start
./mac-bridge.sh check

Windows (PowerShell, normal logged-in user)

uv sync --locked
.\windows-bridge.ps1 install -PublicUrl https://YOUR-HOSTNAME
.\windows-bridge.ps1 start
.\windows-bridge.ps1 check

Windows installs a scheduled task for only the current user's interactive session, at login. It is not a Windows service. It does not store a Windows password or request administrator privileges. GUI tools require the same active, unlocked desktop; they do not work through Session 0, the UAC secure desktop, or an unavailable/locked session. Do not elevate the launcher as a blanket fix. If local policy blocks unsigned scripts, review it with your administrator; this project does not disable policy or supply an execution-policy bypass.

Use your real HTTPS hostname only in the private installation command/configuration. The launcher stores settings in ~/.vbridge/settings.json and installs the user LaunchAgent on macOS or per-user logon task on Windows. It refuses to replace an existing launcher without explicit permission. The server binds to loopback (default port 8799); the launcher publishes named OAuth/MCP paths on standard HTTPS port 443. It preserves unrelated Funnel routes and refuses conflicting paths. This is not an arbitrary reverse-proxy installer.

Run ./mac-bridge.sh connector or .\windows-bridge.ps1 connector for your local connector URL. In Claude settings, add VBridge, select Sign in now and automatic OAuth registration, and leave request headers empty. Read ~/.vbridge/passphrase privately and approve the authorization page. The command does not print the passphrase. OAuth uses authorization-code PKCE and refresh grants. URL-embedded bearer credentials are not supported. Do not enter an inference provider key.

See RUNBOOK.md for permissions, recovery, and safe checks. See CAPABILITIES.md for tools, limits, performance, and the current verification boundary.

Tools

• ping, bridge_status: service and backend checks.

• run_command, read_file, write_file: direct local actions. run_applescript is macOS-only.

• start_job, job_status, list_jobs, cancel_job: bounded background shell jobs. These are process jobs, not model delegation.

• Optional platform UI tools: display/app discovery, screenshot, focus, click, typing, key presses, and clipboard. permission_status preflight is always available. UI action tools are disabled by default; enable ui_enabled in private settings only after reviewing the risks.

• Configured Desktop stdio servers and enabled Desktop extensions are exported with backend namespaces. Catalog size and permissions depend on your installation.

The optional queue_task/task_status/recent_tasks path delegates to Claude Code. It is hidden unless VBRIDGE_ENABLE_WORKER=1 is set. It requires a separately configured worker and may use paid inference or a subscription. Installing or starting this launcher does not start that worker.

Verify before publishing or using

uv run --locked python tests/direct.py
uv run --locked pytest -q
uv run --locked python scripts/privacy_audit.py
./mac-bridge.sh check        # Explicit live OAuth/direct-shell check
./mac-bridge.sh permissions  # Explicit live permission preflight

tests/public_direct.py --live is an explicit opt-in wrapper for the live check. Live checks reuse a private operator client registration, get fresh PKCE tokens, and revoke the grant afterward. They do not call paid inference, send messages, or take screenshots. On macOS, permission preflight opens the Messages database for access only; it does not read contents. On Windows, permission preflight checks session/desktop availability only. Screenshots and UI action delivery require separate, owner-approved live tests. App schema discovery alone does not prove app actions work.

Emergency stop: ./mac-bridge.sh stop or .\windows-bridge.ps1 stop. This sets ~/.vbridge/DISABLED and stops the platform launcher. It cannot undo actions or stop an already-running detached process. Private state, logs, credentials, backups, and archived live tests belong outside the checkout under ~/.vbridge/. The privacy audit is a guardrail, not a guarantee; review all candidate files and repository history before any publication.

Release checks and license

The CI workflow covers macOS and Windows with Python 3.12 and 3.13. It installs locked dependencies, runs offline tests/lint/privacy checks, and builds packages. A workflow file is not proof that those jobs passed. Interactive screenshot/input, Task Scheduler permissions, live Funnel/OAuth, and Voice checks are separate owner-approved validation. No CI job signs in, starts a public service, or reads personal Desktop state. See RELEASE_READINESS.md.

Licensed under MIT. See THIRD_PARTY.md for external packages, installed extensions, and redistribution limits.