DesktopBridge 🌉

Local Model Context Protocol server for macOS. Claude (or any MCP host) talks to it over stdio and can:

• Read, write, list, and search files inside allowlisted directories

• Read CPU / memory / disk stats, uptime, and a redacted environment

• List running applications

• Run shell commands with separate stdout/stderr, timeouts, and optional progress streaming

• Read and write the clipboard

• Capture screenshots and list displays

This process has the same OS rights as the user who launched it. Treat it like giving the model a terminal on your Mac, then shrink that blast radius with DESKTOP_BRIDGE_ROOTS.

Requirements

• macOS (clipboard, screenshots, and application listing use Apple tools)

• Node.js 20.19+ (22 LTS recommended)

Related MCP server: macOS Automator MCP Server

Install

cd desktop-bridge
npm install
npm run build
npm test

The compiled entrypoint is dist/index.js.

Connect to Claude Desktop

1. Build the server (npm run build).

2. Open Claude Desktop → Settings → Developer → Edit Config.

3. Merge the block from claude_desktop_config.example.json, replacing the path and usernames:

{
  "mcpServers": {
    "desktop-bridge": {
      "command": "node",
      "args": ["/Users/YOU/dev/desktop-bridge/dist/index.js"],
      "env": {
        "DESKTOP_BRIDGE_ROOTS": "/Users/YOU/Desktop,/Users/YOU/Documents,/Users/YOU/Downloads"
      }
    }
  }
}

4. Fully quit and reopen Claude Desktop.

5. Confirm desktop-bridge appears under MCP tools (bridge icon 🌉).

Config file on macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Connect to Claude Code

claude mcp add desktop-bridge -- node /Users/YOU/dev/desktop-bridge/dist/index.js

Or add the same command / args / env block to ~/.claude.json.

Connect to Cursor

Add to ~/.cursor/mcp.json (or the project .cursor/mcp.json):

{
  "mcpServers": {
    "desktop-bridge": {
      "command": "node",
      "args": ["/Users/YOU/dev/desktop-bridge/dist/index.js"]
    }
  }
}

Smoke-test without a host

npm run inspector

That launches the MCP Inspector against the built stdio server. Call list_roots, then get_system_info.

Logs go to stderr only. Do not console.log in this process — stdout is the JSON-RPC channel.

Environment

Copy .env.example for a commented template. The server reads process env (Claude Desktop env block), not a .env file.

Tools

Resources: desktop://roots, desktop://system/info.
Prompts: inspect_desktop, find_file.

Security model

• Files: every path is realpath'd. The resolved path must stay inside a configured root. .., extra slashes, and symlinks that escape are rejected.

• Home is not a default root. That keeps ~/.ssh and similar out of reach until you add them on purpose.

• Shell: still a full user shell. A command can cd anywhere even when cwd is restricted. Disable it with DESKTOP_BRIDGE_ALLOW_SHELL=false if you only want file/clipboard/screen tools.

• Env: keys matching password/token/secret/key/credential/cookie/session are replaced with [redacted].

• Stdio: no network listener. The host spawns this process.

macOS permissions

If screencapture fails, open System Settings → Privacy & Security → Screen Recording and enable the host app, then restart it.

Development

npm run build    # tsc → dist/
npm start        # node dist/index.js (stdio)
npm test         # compile + node:test

Layout: src/lib/* (path guard, process runner, glob/search), src/tools/* (MCP tools), src/index.ts (stdio entry).

Home

https://home.jameymcelveen.com is the browser start page (web/, no extra npm packages). Sign-in is @mcelveen.us plus STATUS_PASSWORD.

What is there today, and the dump tray for whatever comes next:

Set Chrome/Safari/Firefox homepage to https://home.jameymcelveen.com (browsers will not let the page do it for you). Session cookie lasts 30 days. / focuses search; ⌘K too.

Push to main runs CI, then deploys Vercel (the site) and Railway (heartbeat + saved config).

On the Mac, add to the MCP server env:

DESKTOP_BRIDGE_STATUS_URL=https://home.jameymcelveen.com/api/heartbeat
DESKTOP_BRIDGE_STATUS_TOKEN=<HEARTBEAT_TOKEN>

License

MIT