bridgedesk

# BridgeDesk ## About BridgeDesk is a desktop launcher and local MCP workspace server for ChatGPT and other MCP clients. It lets a trusted MCP client work with selected local project folders through explicit tools for reading, editing, searching, running commands, and showing changes. BridgeDesk is Windows-first. It is designed for local development workflows where you choose one approved project folder, start the BridgeDesk server, and connect an MCP-capable client through the generated MCP URL. ## Download BridgeDesk For normal Windows use, download the latest installer from GitHub Releases: ```text https://github.com/stanic-mah/bridgedesk/releases/latest/download/BridgeDesk-Setup.exe ``` The installer build supports BridgeDesk's in-app update checks. A portable exe is also attached to each release for manual use, but the installer is the recommended download. BridgeDesk has two entrypoints: - an Electron desktop launcher for setup, tunnels, process control, and copyable connection details - a CLI and MCP server for headless or scripted use ## Requirements - Node `>=20.12 <27` - npm - Git - Bash-compatible shell; Git Bash is the simplest Windows option - Optional: `cloudflared` for the launcher-managed quick tunnel ## Desktop Launcher Install dependencies and start the launcher from a local checkout: ```bash npm install npm run desktop ``` The launcher checks local requirements, lets you choose one project folder, starts a Cloudflare tunnel when available, starts the BridgeDesk server, and copies the MCP URL and Owner password for the MCP client. BridgeDesk supports two tunnel modes: - Quick Tunnel: easiest setup. Cloudflare gives BridgeDesk a temporary `trycloudflare.com` URL, and that URL changes when the tunnel is restarted. - Permanent Tunnel: best for regular use. BridgeDesk uses your Cloudflare account, domain, and named tunnel so the MCP URL can stay fixed, for example `https://mcp.yourdomain.com/mcp`. Use Permanent Tunnel if you do not want to re-add the MCP server in ChatGPT after closing the app or restarting the computer. For step-by-step setup, including Cloudflare Tunnel installation, Permanent Tunnel setup, ChatGPT connection, and troubleshooting, see [docs/user-guide.md](docs/user-guide.md). Important Cloudflare note: if ChatGPT fails after you enter the BridgeDesk owner password, turn off Cloudflare Bot Fight Mode for the BridgeDesk domain. Bot Fight Mode can block ChatGPT's OAuth requests before they reach BridgeDesk. If Cloudflare Tunnel is not installed, paste any HTTPS tunnel URL into the launcher. The URL should point to: ```text http://127.0.0.1:7676 ``` Use this MCP endpoint in the client: ```text https://your-tunnel-host.example.com/mcp ``` ## CLI Build and run locally: ```bash npm install npm run build node dist/cli.js init node dist/cli.js serve ``` After publishing or linking the package, the public command is: ```bash bridgedesk init bridgedesk serve bridgedesk doctor bridgedesk config get bridgedesk config set publicBaseUrl https://your-tunnel-host.example.com ``` The default local endpoint is: ```text http://127.0.0.1:7676/mcp ``` ## Configuration BridgeDesk stores local configuration in: ```text ~/.bridgedesk/config.json ~/.bridgedesk/auth.json ``` Important environment variables: - `BRIDGEDESK_PUBLIC_BASE_URL` - `BRIDGEDESK_ALLOWED_ROOTS` - `BRIDGEDESK_OAUTH_OWNER_TOKEN` - `BRIDGEDESK_STATE_DIR` - `BRIDGEDESK_WORKTREE_ROOT` - `BRIDGEDESK_TOOL_MODE` See [docs/configuration.md](docs/configuration.md) for the full reference. ## Security BridgeDesk is powerful local access to selected folders on your machine. Keep allowed roots narrow, protect `auth.json`, and connect only trusted MCP clients. The desktop launcher rejects drive roots and the whole user folder as project roots. See [docs/security.md](docs/security.md) for the full model. ## Development ```bash npm install npm run typecheck npm test npm run build npm run desktop ``` The build produces: - `dist/cli.js` for the CLI - `dist/server.js` for the MCP server - `dist/ui` for MCP app widgets - `dist/desktop` for the Electron launcher ## License BridgeDesk is distributed under the MIT License. See [LICENSE](LICENSE).