macos-ui-mcp

Claude가 macOS 네이티브 앱의 UI를 빌드하는 동안 검사하고 제어할 수 있게 해주는 Playwright 스타일 도구 — 화면 기록 권한 없이.

화면을 캡처하는 대신, 앱이 스스로를 렌더링합니다. 디버그 전용의 작은 Swift 패키지(swift-harness/)가 앱의 뷰 트리와 인프로세스 PNG 렌더러를 localhost HTTP로 노출하고, MCP 서버(src/)가 이를 Claude가 호출할 수 있는 도구로 변환합니다: list_windows, get_ui_tree, screenshot, click, type, wait_for, invoke_action.

설계 근거, 아키텍처 비교, 프로젝트 목표는 IDEA.md를 참조하세요.

Claude Code ──MCP(stdio)──> macos-ui-mcp server ──HTTP──> AppMCPHarness (in your app, DEBUG only)

레이아웃

Related MCP server: Desktop Pilot MCP

사용 방법

1. macOS 앱에 하네스 추가 (DEBUG 빌드 전용)

swift-harness/README.md를 참조하세요. AppDelegate에 한 줄만 추가하면 됩니다:

#if DEBUG
AppMCP.start()   // opens http://127.0.0.1:8787
#endif

2. MCP 서버 빌드

npm install
npm run build

3. Claude Code에 등록

// .mcp.json
{
  "mcpServers": {
    "macos-ui-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macos-ui-mcp/dist/index.js"],
      "env": { "MACOS_UI_MCP_HARNESS_URL": "http://127.0.0.1:8787" }
    }
  }
}

이제 디버그 빌드로 앱을 실행한 상태에서 Claude에게 get_ui_tree 또는 screenshot을 호출하도록 요청하세요 — 화면 기록 권한 프롬프트가 없습니다.

개발

npm test           # 38 unit tests, no real app needed (mock harness); e2e is skipped
npm run typecheck
npm run dev         # run the server against a live harness

npm run test:e2e    # builds showcase/, launches it, runs the real tools against the
                    # real Swift harness. Needs a logged-in macOS GUI session.

npm run test:e2e는 목표의 증거입니다: get_ui_tree가 컨트롤을 보는지, screenshot이 실제 인프로세스 PNG를 반환하는지, click / type이 라이브 UI를 변경하는지 확인합니다 — 화면 기록 권한 없이.

선택자 문법

click, type, screenshot, wait_for에서 사용:

click / type은 모호한 선택자(일치 항목이 둘 이상)를 거부하고 후보 id를 보고합니다.

상태

• v0.1 — macOS / AppKit. 7개 도구 모두 구현됨. 38개의 단위 테스트 + 실제 Swift 하네스를 통해 showcase/ 앱을 구동하는 5개 사례의 엔드투엔드 테스트. 검증됨: 트리, 인프로세스 PNG 스냅샷, 탭, 텍스트 설정, 액션 훅 — 화면 기록 꺼짐.

• 아직 아님 — SwiftUI 네이티브 트리(현재는 AppKit 인트로스펙션만), Windows 어댑터, 접근성 API를 통한 타사 앱 검사.

라이선스

MIT © 2026 Thang Duong

macos-ui-mcp