DesktopBridge
DesktopBridge is a macOS Model Context Protocol server that gives an MCP host local control over files, system monitoring, shell, clipboard, and display/screenshot tools. Capabilities include:
File operations: read/write/list/search files within allowlisted roots only.
System information: get CPU/memory/disk stats, host info, uptime, and redacted environment variables.
Process/app info: list running (optionally background) macOS applications.
Shell execution: run shell commands with captured stdout/stderr, timeout, optional streaming, and cwd restrictions.
Clipboard: read and write the macOS clipboard text.
Display/screenshot: list display details and capture screen PNGs (requires Screen Recording permission).
Network info: retrieve public and LAN IPv4 addresses.
Resources/prompts: exposes
desktop://rootsanddesktop://system/inforesources, plusinspect_desktopandfind_fileprompts.
Allows integration with the local macOS environment, providing tools to read/write/search files in allowlisted directories, run shell commands, gather system stats and info, list running applications, manage the clipboard, and capture screenshots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DesktopBridge What's the current CPU and memory usage on my Mac?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 testThe compiled entrypoint is dist/index.js.
Connect to Claude Desktop
Build the server (
npm run build).Open Claude Desktop → Settings → Developer → Edit Config.
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"
}
}
}
}Fully quit and reopen Claude Desktop.
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.jsOr 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 inspectorThat 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
Variable | Default | Meaning |
|
| Comma-separated directories file tools may touch. The OS temp dir is always added so screenshots have a place to land. |
|
| Max size for a single file read/write (1 KiB–100 MiB). |
|
| Default |
|
| Combined stdout+stderr capture cap. Excess output kills the process and sets |
|
| Set |
|
| When true, |
| unset | Heartbeat POST URL for the status site ( |
| unset | Bearer token matching the site’s |
|
| Heartbeat interval (5s–5m). |
Copy .env.example for a commented template. The server reads process env (Claude Desktop env block), not a .env file.
Tools
Tool | What it does |
| Allowed directories and file-size cap |
| Text (optional line window) or base64 |
| Create/overwrite/append; optional |
| Name, type, size, mtime, mode |
| Glob on names and/or regex on file contents |
| CPU %, load, memory, |
| Host, uptime, user, redacted env |
| GUI (or all) processes via System Events |
| Shell with split stdout/stderr; |
|
|
| Display name, main flag, scale, frame |
| PNG via |
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
~/.sshand similar out of reach until you add them on purpose.Shell: still a full user shell. A command can
cdanywhere even when cwd is restricted. Disable it withDESKTOP_BRIDGE_ALLOW_SHELL=falseif 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
Feature | Permission |
Screenshots | Screen Recording for the app that spawned Node (Claude Desktop, Cursor, or Terminal) |
| Automation → System Events if macOS prompts |
Accessibility-heavy apps | may still hide titles; the tool lists process names either way |
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:testLayout: 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/). Widgets are Lit web components under web/public/components/, tagged jm-*. The isolated catalog is Storybook at https://home.jameymcelveen.com/storybook/ (cd web && npm run storybook locally). Lit is vendored into web/public/vendor/ (npm run vendor / postinstall). Sign-in is @mcelveen.us plus STATUS_PASSWORD.
What is there today, and the dump tray for whatever comes next:
Piece | Notes |
Widgets | Lit web components, |
Search | Autofocus. Google completions as you type (same suggestion feed as google.com). Kagi / DDG. Bangs: |
Links | Same tiles as the local landing-page app, plus the properties. Edit as JSON in Settings |
Weather | Open-Meteo, °F, Florence SC unless you override coords |
Mac | DesktopBridge heartbeat: online / stale / offline, IPs, load |
VIN Sweep | Client-side NHTSA decode / recalls / complaints, plus human-only NICB / FL title / iSeeCars taps |
Scratch | Autosaved notes |
Word | Daily verse |
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
Available Tools
14 toolsget_display_infoGet display infoARead-onlyIdempotent
List attached displays: name, main flag, scale factor, and frame in Cocoa points.
Inputs: no named parameters.
get_network_infoGet network infoARead-onlyIdempotent
Public IPv4 (via ipify) and non-internal LAN IPv4 addresses. Use this to record the home WAN address on the status site.
Inputs: no named parameters.
get_system_infoGet system infoARead-onlyIdempotent
Hostname, OS, architecture, uptime, user, home, and environment variables. Secret-looking keys are redacted.
Inputs: no named parameters.
get_system_statsGet system statsBRead-onlyIdempotent
CPU percent (short sample), load average, memory, and disk usage (df -kP).
Inputs: no named parameters.
list_applicationsList running applicationsARead-onlyIdempotent
Foreground macOS application processes from System Events (name, pid, visible). includeBackground includes agents.
Inputs: includeBackground.
list_directoryList directoryARead-onlyIdempotent
List files and subdirectories with type, size, modified time, and mode.
Inputs: path (required).
list_rootsList allowed rootsARead-onlyIdempotent
List directories this server may read and write. File tools reject paths outside these roots.
Inputs: no named parameters.
read_clipboardRead clipboardARead-onlyIdempotent
Read the current macOS clipboard as text (pbpaste).
Inputs: no named parameters.
read_fileRead fileARead-onlyIdempotent
Read a file inside an allowed root. Use encoding=base64 for binary. offset/limit are 1-based line numbers for utf8.
Inputs: path (required), limit, offset, encoding.
run_commandRun shell commandADestructive
Run a command with the user shell. stdout and stderr are captured separately. stream=true sends MCP progress notifications as output arrives. cwd must be inside an allowed root unless DESKTOP_BRIDGE_RESTRICT_SHELL_CWD=false.
Inputs: command (required), cwd, stream, timeoutMs.
search_filesSearch filesARead-onlyIdempotent
Walk an allowed directory. namePattern is a glob (* and **). contentPattern is a JavaScript regex matched per line. Symlinks are not followed.
Inputs: path (required), maxResults, namePattern, contentFlags, +1 more.
take_screenshotTake screenshotBRead-only
Capture the screen with screencapture. display is the 1-based display id (-D). Saves PNG under an allowed path (default: a timestamped file in the temp dir). Requires Screen Recording permission for the host app that launched this server.
Inputs: path, display, includeCursor.
write_clipboardWrite clipboardADestructiveIdempotent
Replace the macOS clipboard with the given text (pbcopy).
Inputs: text (required).
write_fileWrite fileADestructive
Create or overwrite a file inside an allowed root. createDirectories mkdir -p the parent. append adds to an existing file.
Inputs: path (required), content (required), append, encoding, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have clearly distinct purposes, but a few pairs like get_system_stats vs get_system_info and list_directory vs search_files could be confused without careful reading. Descriptions clarify the differences, so overall ambiguity is low.
All 14 tools follow a consistent verb_noun snake_case naming convention (e.g., list_roots, read_file, get_network_info). This pattern is uniform and predictable, making it easy for agents to infer behavior.
With 14 tools, the server covers a broad range of desktop automation functions—file, system, clipboard, apps, network, command, and display—without being bloated. Each tool has a clear purpose, and the count is well within the ideal range.
The toolset covers core file operations (read, write, list, search) but misses common operations like delete or rename. It also lacks process management beyond listing apps, but the provided surface is adequate for many automation tasks, leaving only moderate gaps.
Maintenance
Related MCP Connectors
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
EXZA Remote — AI Computer Commander Your computer. Your control. Securely connect your own macOS, Windows or Linux computer to compatible AI clients, including ChatGPT and Claude. EXZA Remote provides 59 MCP tools for authorized file management, terminal operations, system monitoring, desktop automation and email workflows. GETTING STARTED 1. Create an EXZA Remote account. 2. Install the official computer connection client. 3. Pair your device using a temporary six-digit PIN. 4. Approve the connection on your computer. 5. Connect your preferred MCP client using EXZA OAuth. MCP ENDPOINT https://remote.exza.de/mcp TRANSPORT Streamable HTTP with OAuth 2.0 KEY FEATURES • 59 MCP tool interfaces • Secure computer and file access • Terminal commands and background jobs • File search, reading and editing • System monitoring and desktop automation • macOS, Windows and Linux support • Owner-controlled permissions and approvals COMPLETE INSTALLATION & DOCUMENTATION Detailed setup instructions, terminal installation commands, all 59 tools, troubleshooting and security information: https://github.com/exzade/EXZA-Remote/blob/main/docs/GLAMA_OVERVIEW.md Official website: https://remote.exza.de EXZA Remote is an independent, OAuth-protected service. Computer access requires individual account authorization and device-owner approval.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables running AppleScript code to interact with Mac applications and system features including Notes, Calendar, Contacts, Messages, file management, and more.1159 npm469MIT
- AlicenseAqualityFmaintenanceProvides a Model Context Protocol server for executing AppleScript and JavaScript for Automation scripts on macOS, featuring a knowledge base of pre-defined scripts and supporting automation of macOS applications and system functions.2667 npm883MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables execution of AppleScript and JavaScript for Automation scripts on macOS, allowing programmatic control of applications and system functions through a rich knowledge base of pre-defined scripts.29MIT
- FlicenseAqualityDmaintenanceSecure AppleScript execution for AI applications via Model Context Protocol with configurable security profiles and automatic TCC permission handling.31-