Skip to main content
Glama

DesktopBridge 🌉

CI Home Node License: MIT

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"
      }
    }
  }
}
  1. Fully quit and reopen Claude Desktop.

  2. 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

Variable

Default

Meaning

DESKTOP_BRIDGE_ROOTS

~/Desktop, ~/Documents, ~/Downloads (if they exist)

Comma-separated directories file tools may touch. The OS temp dir is always added so screenshots have a place to land.

DESKTOP_BRIDGE_MAX_FILE_BYTES

10485760

Max size for a single file read/write (1 KiB–100 MiB).

DESKTOP_BRIDGE_COMMAND_TIMEOUT_MS

30000

Default run_command timeout (100–300000).

DESKTOP_BRIDGE_MAX_OUTPUT_BYTES

1048576

Combined stdout+stderr capture cap. Excess output kills the process and sets truncated.

DESKTOP_BRIDGE_ALLOW_SHELL

true

Set false to disable run_command.

DESKTOP_BRIDGE_RESTRICT_SHELL_CWD

true

When true, run_command cwd must sit inside an allowed root.

DESKTOP_BRIDGE_STATUS_URL

unset

Heartbeat POST URL for the status site (…/api/heartbeat).

DESKTOP_BRIDGE_STATUS_TOKEN

unset

Bearer token matching the site’s HEARTBEAT_TOKEN.

DESKTOP_BRIDGE_STATUS_INTERVAL_MS

15000

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

list_roots

Allowed directories and file-size cap

read_file

Text (optional line window) or base64

write_file

Create/overwrite/append; optional mkdir -p

list_directory

Name, type, size, mtime, mode

search_files

Glob on names and/or regex on file contents

get_system_stats

CPU %, load, memory, df

get_system_info

Host, uptime, user, redacted env

list_applications

GUI (or all) processes via System Events

run_command

Shell with split stdout/stderr; stream → progress notifications

read_clipboard / write_clipboard

pbpaste / pbcopy

get_display_info

Display name, main flag, scale, frame

take_screenshot

PNG via screencapture; returns an image block when ≤ 5 MiB

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

Feature

Permission

Screenshots

Screen Recording for the app that spawned Node (Claude Desktop, Cursor, or Terminal)

list_applications

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: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/). 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, jm-* prefix. Isolated catalog: Storybook

Search

Autofocus. Google completions as you type (same suggestion feed as google.com). Kagi / DDG. Bangs: !g !k !d !gh !yt !w !maps

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 tools
get_display_infoGet display infoA
Read-onlyIdempotent

List attached displays: name, main flag, scale factor, and frame in Cocoa points.

Inputs: no named parameters.

get_network_infoGet network infoA
Read-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 infoA
Read-onlyIdempotent

Hostname, OS, architecture, uptime, user, home, and environment variables. Secret-looking keys are redacted.

Inputs: no named parameters.

get_system_statsGet system statsB
Read-onlyIdempotent

CPU percent (short sample), load average, memory, and disk usage (df -kP).

Inputs: no named parameters.

list_applicationsList running applicationsA
Read-onlyIdempotent

Foreground macOS application processes from System Events (name, pid, visible). includeBackground includes agents.

Inputs: includeBackground.

list_directoryList directoryA
Read-onlyIdempotent

List files and subdirectories with type, size, modified time, and mode.

Inputs: path (required).

list_rootsList allowed rootsA
Read-onlyIdempotent

List directories this server may read and write. File tools reject paths outside these roots.

Inputs: no named parameters.

read_clipboardRead clipboardA
Read-onlyIdempotent

Read the current macOS clipboard as text (pbpaste).

Inputs: no named parameters.

read_fileRead fileA
Read-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 commandA
Destructive

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 filesA
Read-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 screenshotB
Read-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 clipboardA
DestructiveIdempotent

Replace the macOS clipboard with the given text (pbcopy).

Inputs: text (required).

write_fileWrite fileA
Destructive

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

    A3.8/5.0

    Scored across 14 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    • Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.

      https://mcp.sentry.dev/mcp
    • 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.

      https://remote.exza.de/mcp
    • Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.

      https://mcp.sentinelx.app/mcp/mcp
    • A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      Provides 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.
      2
      667 npm
      883
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      2
      9
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Secure AppleScript execution for AI applications via Model Context Protocol with configurable security profiles and automatic TCC permission handling.
      3
      1
      -