DesktopBridge 🌉

macOS용 로컬 Model Context Protocol 서버입니다. Claude(또는 모든 MCP 호스트)가 stdio를 통해 이 서버와 통신하며 다음 작업을 수행할 수 있습니다:

• 허용된 디렉터리(allowlisted directories) 내 파일 읽기, 쓰기, 나열, 검색

• CPU / 메모리 / 디스크 통계, 가동 시간, 그리고 편집된(redacted) 환경 변수 읽기

• 실행 중인 애플리케이션 나열

• 분리된 stdout/stderr, 타임아웃, 선택적 진행률 스트리밍을 지원하는 셸 명령 실행

• 클립보드 읽기 및 쓰기

• 스크린샷 캡처 및 디스플레이 나열

이 프로세스는 프로세스를 실행한 사용자와 동일한 OS 권한을 가집니다. 모델에게 Mac에서 터미널을 하나 준다고 생각하고, DESKTOP_BRIDGE_ROOTS로 피해 범위를 줄이세요.

요구 사항

• macOS(클립보드, 스크린샷, 애플리케이션 나열은 Apple 도구 사용)

• Node.js 20.19+ (22 LTS 권장)

Related MCP server: macOS Automator MCP Server

설치

cd desktop-bridge
npm install
npm run build
npm test

컴파일된 진입점은 dist/index.js입니다.

Claude Desktop에 연결

1. 서버를 빌드합니다(npm run build).

2. Claude Desktop → Settings → Developer → Edit Config를 엽니다.

3. claude_desktop_config.example.json의 블록을 병합하고 경로와 사용자 이름을 바꿉니다:

{
  "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. Claude Desktop을 완전히 종료하고 다시 엽니다.

5. MCP 도구(브리지 아이콘 🌉) 아래에 desktop-bridge가 나타나는지 확인합니다.

macOS의 설정 파일:

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

Claude Code에 연결

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

또는 동일한 command / args / env 블록을 ~/.claude.json에 추가합니다.

Cursor에 연결

~/.cursor/mcp.json(또는 프로젝트의 .cursor/mcp.json)에 추가합니다:

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

호스트 없이 스모크 테스트

npm run inspector

이 명령은 빌드된 stdio 서버에 대해 MCP Inspector를 실행합니다. list_roots를 호출한 다음 get_system_info를 호출하세요.

로그는 stderr로만 출력됩니다. 이 프로세스에서 console.log를 사용하지 마세요 — stdout은 JSON-RPC 채널입니다.

환경 변수

주석이 달린 템플릿은 .env.example을 복사하세요. 서버는 .env 파일이 아닌 프로세스 환경 변수(Claude Desktop env 블록)를 읽습니다.

도구

리소스: desktop://roots, desktop://system/info.
프롬프트: inspect_desktop, find_file.

보안 모델

• 파일: 모든 경로는 realpath로 확인됩니다. 확인된 경로는 구성된 루트 안에 있어야 합니다. .., 추가 슬래시, 루트를 벗어나는 심볼릭 링크는 거부됩니다.

• 홈 디렉터리는 기본 루트가 아닙니다. 이렇게 하면 의도적으로 추가하기 전까지 ~/.ssh 및 유사한 디렉터리에 접근할 수 없습니다.

• 셸: 여전히 전체 사용자 셸입니다. cwd가 제한되어 있어도 명령은 어디로든 cd할 수 있습니다. 파일/클립보드/화면 도구만 원한다면 DESKTOP_BRIDGE_ALLOW_SHELL=false로 비활성화하세요.

• 환경 변수: password/token/secret/key/credential/cookie/session과 일치하는 키는 [redacted]로 대체됩니다.

• Stdio: 네트워크 리스너가 없습니다. 호스트가 이 프로세스를 생성합니다.

macOS 권한

screencapture가 실패하면 시스템 설정 → 개인정보 보호 및 보안 → 화면 기록을 열고 호스트 앱을 활성화한 다음 다시 시작하세요.

개발

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

구성: src/lib/* (경로 가드, 프로세스 실행기, glob/검색), src/tools/* (MCP 도구), src/index.ts (stdio 진입점).

홈

https://home.jameymcelveen.com은 브라우저 시작 페이지입니다(web/, 추가 npm 패키지 없음). 로그인은 @mcelveen.us와 STATUS_PASSWORD를 사용합니다.

현재 제공되는 기능과 앞으로 추가될 기능을 위한 덤프 트레이:

Chrome/Safari/Firefox 홈페이지를 https://home.jameymcelveen.com으로 설정하세요(브라우저가 페이지가 직접 설정하는 것을 허용하지 않습니다). 세션 쿠키는 30일 동안 유지됩니다. /는 검색에 포커스합니다. ⌘K도 동일합니다.

main에 푸시하면 CI가 실행된 후 Vercel(사이트)과 Railway(하트비트 + 저장된 설정)에 배포됩니다.

Mac에서 MCP 서버 환경 변수에 추가하세요:

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

라이선스

MIT