AI 클라이언트가 앱 접근성 트리, 윈도우, 입력, 브라우저, 화면 캡처, OCR 및 Apple 앱을 제어하여 macOS를 자동화할 수 있게 합니다.
다른 이름 AdelElo13/mac-control-mcp
- 스타
- 18
- Tools
- 10
- 다운로드, 30일
- —
- 최신 버전
- 0.10.3
- 마지막 커밋
- 2026년 10월 16일
- 라이선스
- MIT
mac-control MCP란?
mac-control은(는) MCP server입니다. AI 클라이언트가 앱 접근성 트리, 윈도우, 입력, 브라우저, 화면 캡처, OCR 및 Apple 앱을 제어하여 macOS를 자동화할 수 있게 합니다. 10개 도구를 제공합니다. 예: capture_screen, capture_screen_v2, capture_window.
프로젝트 README에서 생성된 요약
mac-control MCP server 정보
mac-control-mcp를 사용하면 AI 클라이언트 내부에서 macOS 데스크톱 작업을 자동화할 수 있습니다. 이 네이티브 Swift 서버는 153개의 도구를 제공하여 Claude Desktop, Claude Code, Cursor와 같은 호환 클라이언트가 운영체제와 직접 상호작용할 수 있도록 지원합니다. stdio를 통해 로컬에서 작동하며 macOS 14.0 이상이 필요합니다. 사용자는 서명된 .app 번들로 설치하거나 npm을 통해 설치하여 AI 에이전트에게 컴퓨터 제어 권한을 부여할 수 있습니다.
개발자는 이 서버를 사용하여 Safari 및 Chrome과 같은 웹 브라우저를 제어하고, 애플리케이션 라이프사이클을 관리하며, 윈도우를 조작할 수 있습니다. 이 서버에는 접근성 트리를 읽고, 화면 콘텐츠에 대해 OCR을 수행하며, 시스템 클립보드를 관리하는 특화된 기능이 포함되어 있습니다. 또한 Apple 전용 애플리케이션과 통합되어 이메일 전송, 캘린더 이벤트 생성, 리마인더 관리 등을 수행합니다. 네이티브 Swift 구현체이므로 설치 후에는 Python이나 Node 런타임 없이도 작동합니다.
활용 사례
- 1웹 브라우저 탐색 자동화AI 클라이언트가 Safari 또는 Chrome에서 새 탭을 열고, 특정 URL로 이동하며, JavaScript를 실행할 수 있습니다.
- 2데스크톱 애플리케이션 상호작용접근성 트리를 사용하여 실행 중인 모든 애플리케이션 내에서 특정 버튼이나 텍스트 필드를 찾도록 AI에게 지시할 수 있습니다.
- 3이미지에서 텍스트 추출개발자가 AI에게 화면의 특정 부분을 확인하고 시각적 텍스트를 디지털 데이터로 변환하도록 요청할 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
mac-control MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 mac-control MCP 설치
$ claude mcp add mac-control-mcp -- npx -y mac-control-mcpCursor에 mac-control MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"mac-control-mcp": {
"command": "npx",
"args": [
"-y",
"mac-control-mcp"
]
}
}
}VS Code에 mac-control MCP 설치
.vscode/mcp.json
{
"servers": {
"mac-control-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mac-control-mcp"
]
}
}
}VS Code CLI에 mac-control MCP 설치
$ code --add-mcp '{"name":"mac-control-mcp","type":"stdio","command":"npx","args":["-y","mac-control-mcp"]}'Claude Desktop에 mac-control MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"mac-control-mcp": {
"command": "npx",
"args": [
"-y",
"mac-control-mcp"
]
}
}
}Codex에 mac-control MCP 설치
$ codex mcp add mac-control-mcp -- npx -y mac-control-mcpCodex config.toml에 mac-control MCP 설치
~/.codex/config.toml
[mcp_servers.mac-control-mcp] command = "npx" args = ["-y", "mac-control-mcp"]
Gemini CLI에 mac-control MCP 설치
$ gemini mcp add -s user mac-control-mcp npx -- -y mac-control-mcpGemini settings.json에 mac-control MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"mac-control-mcp": {
"command": "npx",
"args": [
"-y",
"mac-control-mcp"
]
}
}
}mac-control MCP 도구 10
README에서 감지됨capture_screencapture_screen_v2capture_windowcapture_displaylist_elementsfind_elementfind_elementsquery_elementsget_ui_treeax_tree_augmented
| capture_screen | — | |
| capture_screen_v2 | — | |
| capture_window | — | |
| capture_display | — | |
| list_elements | — | |
| find_element | — | |
| find_elements | — | |
| query_elements | — | |
| get_ui_tree | — | |
| ax_tree_augmented | — |
구성
NOTARIZE_PROFILE
| 이름 | 설명 | 유형 |
|---|---|---|
| NOTARIZE_PROFILE | — |
자동 검사
2026년 11월 12일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨통과
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음통과
README
GitHub에서 보기mac-control-mcp
Native Swift MCP server for full macOS automation. 153 tools in one signed .app bundle — no Python, no Node runtime, no Electron. Full list with parameters: docs/TOOLS.md.
Gives any MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.) the ability to:
- Read and mutate the Accessibility tree of any running app
- Drive Safari and Chrome (tabs, navigation, JS eval)
- Capture the screen, a display, or a specific window (ScreenCaptureKit)
- OCR what's on screen
- Click, type, scroll, drag, send key events
- Control windows (move / resize / fullscreen / minimize / main)
- Manage the clipboard
- Launch / activate / quit apps
- Search Spotlight's index (NSMetadataQuery) and launch results
- Toggle dark mode, volume, list displays, inspect menus
Install
Requires macOS 14.0+. Four options, in order of simplicity:
1. One-click install (Claude Desktop, recommended)
The server is published as an MCP Bundle — a zip with a manifest.json that Claude Desktop reads directly:
- Download mac-control-mcp-v<version>.mcpb from the latest release.
- Double-click the
.mcpbfile. Claude Desktop opens an install dialog. - Click Install. The server is registered under the name
mac-control-mcpand available immediately in new chats. - First tool call triggers the macOS TCC consent prompts (Screen Recording, Accessibility, Apple Events). Grant all three once — the bundle is Developer-ID signed and notarized, so grants persist across updates.
It's also listed on the official MCP Registry as io.github.AdelElo13/mac-control-mcp, so any MCP client that supports the registry will find it by searching for "mac-control".
2. Install via npm / npx
For clients that are configured with a command line rather than a file path. The npm package mac-control-mcp is a thin launcher: it has no runtime dependencies, and on install it downloads the notarized MacControlMCP.app for that exact version from this repo's GitHub release, verifies it against the published .sha256, refuses any archive entry that escapes the install directory, and re-checks the bundle with codesign --verify --deep --strict, spctl --assess --type execute and a pinned Team ID (A3W973JZ49). The first run therefore pulls ~3 MB; later runs are local.
Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"mac-control-mcp": {
"command": "npx",
"args": ["-y", "mac-control-mcp"]
}
}
}
Claude Code:
claude mcp add mac-control-mcp -- npx -y mac-control-mcp
Cursor — ~/.cursor/mcp.json:
{
"mcpServers": {
"mac-control-mcp": {
"command": "npx",
"args": ["-y", "mac-control-mcp"]
}
}
}
ChatGPT (developer mode, local MCP connector) — mcp.json:
{
"mcpServers": {
"mac-control-mcp": {
"command": "npx",
"args": ["-y", "mac-control-mcp"],
"transport": "stdio"
}
}
}
Two flags are handled by the launcher itself instead of being forwarded to the binary:
npx -y mac-control-mcp --version # version of the bundled .app
npx -y mac-control-mcp --app-path # path to MacControlMCP.app
--app-path is what you need when granting macOS permissions by hand. Note that TCC grants go to the MCP host application that launches this process (Claude Desktop, Cursor, your terminal), not to npx or to the script — run the permissions_status tool once from your client to see which grants are missing and which app they belong to.
MAC_CONTROL_MCP_SKIP_DOWNLOAD=1 skips the download (CI, sandboxed builds); HTTPS_PROXY and NO_PROXY are honoured.
3. Download the prebuilt app
If you don't use Claude Desktop or want manual control:
- Download MacControlMCP-v<version>-macos-universal.tar.gz from the latest release.
- Extract and move
MacControlMCP.appto~/Applications/. - Point your MCP client at the binary inside:
{
"mcpServers": {
"mac-control-mcp": {
"type": "stdio",
"command": "/Users/you/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP"
}
}
}
Add that block to ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop) or ~/.claude.json → mcpServers (Claude Code).
Verify the download with the published SHA-256:
shasum -a 256 MacControlMCP-v<version>-macos-universal.tar.gz
# should match MacControlMCP-v<version>-macos-universal.sha256 on the release
4. Build from source
For contributors or if you want to tweak the code. Requires Swift 6 / Xcode 16+:
git clone https://github.com/AdelElo13/mac-control-mcp.git
cd mac-control-mcp
./scripts/build-bundle.sh
Produces ~/Applications/MacControlMCP.app/Contents/MacOS/MacControlMCP. Without a Developer ID cert in your keychain it'll fall back to ad-hoc signing (works for local use, TCC grants reset on every rebuild).
To re-sign + re-notarise an existing Apple Developer account:
# one-time: store notary credentials in keychain
xcrun notarytool store-credentials "mac-control-mcp" \
--apple-id "you@example.com" --team-id "XXXXXXXXXX"
# subsequent builds:
NOTARIZE_PROFILE=mac-control-mcp ./scripts/build-bundle.sh
Tool surface
Selected categories — this table is a curated subset, not the full list. For the complete, auto-generated tool reference (every tool, its description, and its required/optional parameters, regenerated straight from the tool registry so it can't drift), see docs/TOOLS.md.
| Category | Tools |
|---|---|
| Permissions | permissions_status, request_permissions |
| Accessibility | find_element(s), query_elements, list_elements, get_ui_tree, ax_tree_augmented, get_element_attributes, set_element_attribute, read_value, perform_element_action, wait_for_element, scroll_to_element |
| App lifecycle | list_apps, launch_app, activate_app, quit_app, force_quit_app, wait_for_app, focused_app |
| Windows | list_windows, focus_window, move_window, resize_window, set_window_state, wait_for_window, move_window_to_display |
| Input | click, mouse_event, drag_and_drop, scroll, type_text, press_key, press_key_sequence, key_down, key_up, convert_coordinates |
| Menus | click_menu_path, list_menu_paths, list_menu_titles |
| Browser | browser_list_tabs, browser_get_active_tab, browser_navigate, browser_new_tab, browser_close_tab, browser_eval_js, browser_dom_tree, browser_visible_text, browser_iframes |
| Screen | capture_screen, capture_screen_v2, capture_window, capture_display, ocr_screen |
| Clipboard | clipboard_read, clipboard_write, clipboard_clear |
| Spotlight | spotlight_search, spotlight_open_result |
| System | set_volume, set_dark_mode, list_displays |
| File dialogs | file_dialog_set_path, file_dialog_select_item, file_dialog_confirm, file_dialog_cancel, wait_for_file_dialog |
| Apple apps | mail_send, imessage_send, imessage_list_recent, calendar_create_event, calendar_list_events, reminders_create, reminders_list, contacts_search |
| Voice & recording | speech_to_text, text_to_speech, audio_record, record_screen |
| Undo | undo_last_action, undo_peek |
Which tool when
Several tools overlap in purpose. Based on their actual implementations:
Screen capture — capture_screen vs capture_screen_v2 vs capture_window vs capture_display
capture_screen— main display (or a rectangular region within it) to a PNG file, returns the file path + width/height. Simple, synchronous, no size limits applied.capture_screen_v2— main display only, but stores the PNG as a content-addressed artifact under~/.mac-control-mcp/artifacts/<sha256>.pngand returns{content_ref, bytes, sha256}. Defaults toinline=falseand downscales tomax_dimension/max_bytes(4000px / 4MB by default) specifically to avoid blowing up an MCP client's context window with a huge inline image (referenced in its own description as a fix for claude-code issues #13383/#45785). Prefer this one when the image is going back through an LLM context rather than straight to disk.capture_window— screenshots one specific window by PID (optionally filtered bytitle_contains), not the whole display.capture_display— screenshots one specific physical display by its index fromlist_displays, for multi-monitor setups.
Accessibility tree / element lookup — find_element vs find_elements vs query_elements vs list_elements vs get_ui_tree vs ax_tree_augmented
list_elements— lists actionable elements for a PID (a flat, practical "what can I click" view).find_element— returns the first element matching a role/title filter for a PID.find_elements— same matching asfind_element, but returns all matches, not just the first.query_elements— regex search over role/title/value (falls back to case-insensitive substring on invalid regex); use when a plain role/title filter isn't precise enough.get_ui_tree— walks the full accessibility tree of a process, including containers, and assigns stable element IDs for follow-up calls. Heavier thanlist_elements/find_element(s), but the only one that gives you structure/hierarchy.ax_tree_augmented— likeget_ui_tree, but does one OCR pass and geometrically joins OCR-derived labels onto AX nodes that have no native label. Use it specifically for Electron/Chromium/Canvas apps where the native AX tree is sparse and unlabeled; it's the expensive option (an OCR pass), so reach forget_ui_treefirst and fall back to this when nodes come back unlabeled.
Security model
- Tools that write files (
capture_*,ocr_screen) validateoutput_pathvia a strict allow-list — only the user-scoped temp dir (NSTemporaryDirectory()) and~/Desktop,~/Documents,~/Downloads,~/Picturesare accepted. Symlinks at the target path are rejected to prevent redirection./tmpis deliberately excluded because it's shared across users and opens a TOCTOU window. - AppleScript string interpolation for
browser_eval_jswraps user code in(0, eval)(…)viaJSON.stringify, so quotes/newlines/unicode can't break out of the wrapper. - No network calls. Everything is local system integration.
- Password fields are off limits in code, not by instruction. A field with role or subrole
AXSecureTextFieldnever returns its value or length, and every write route is refused withreason: secure_field: element writes,text_*edits,act, untargetedtype_text, and text keys or Cmd+V viapress_key,press_key_sequenceandkey_downwhile such a field has focus. While such a field has focus, menu-bar and context-menu items (Paste, Start Dictation, Emoji & Symbols) cannot be pressed either; pop-up and combo-box option menus stay usable. Navigation keys (Tab, Return, Escape, arrows) still work, so the agent can hand the field to the user.browser_eval_jsruns arbitrary page JavaScript and is not covered by this guard.
Status (verified in the current release)
| Scope | State |
|---|---|
| Unit / integration test suite | swift test, all green locally and on CI (macos-15) — see ci.yml |
| Live tool probe | A subset of tools exercised end-to-end via real MCP stdio against the running binary, all pass |
| Destructive tools (volume, dark mode, force_quit_app, drag_and_drop, file_dialog_*) | Verified live in a reversible way |
| Code signing | Developer ID Application (A3W973JZ49) with hardened runtime |
| Apple notarization | Accepted by Apple Notary Service, ticket stapled, spctl reports source=Notarized Developer ID |
| Gatekeeper flow | Extracted + launched with the com.apple.quarantine xattr set; no right-click-open needed |
| MCP Registry | Published as io.github.AdelElo13/mac-control-mcp (see server.json for the current version) — distributed as an .mcpb bundle for one-click install |
| Architectures | Universal binary (arm64 + x86_64). Intel slice compiles cleanly but has not been runtime-verified on actual Intel hardware |
move_window_to_display |
Skipped — requires a 2+ display setup |
If you run into an untested path, please open an issue with the reproduction — happy to fix fast.
Caveats
- Cross-origin iframes block
browser_eval_js— same-origin policy, not a limitation of the tool. Use AX coords or synthetic CGEvents for content inside embedded iframes from other origins. - First-run TCC prompts are unavoidable. macOS requires the user to grant Screen Recording, Accessibility and Apple Events the first time. The usage-description strings in
Info.plistmake the consent dialogs show up with a clear reason, but you still need to click Allow in System Settings once.
Development
# Run the test suite
swift test
# Build without packaging
swift build -c release
# Live probe the running binary via MCP stdio
python3 scripts/mcp-sweep.py # if included
License
MIT — see LICENSE.
Contributing
Issues and pull requests welcome. Adversarial reviews especially — prior releases went through 11 rounds of external review before shipping.
mac-control MCP 질문
mac-control MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add mac-control-mcp -- npx -y mac-control-mcp를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
mac-control MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
mac-control MCP는 어떤 도구를 제공하나요?
10개 도구를 제공합니다. 예: capture_screen, capture_screen_v2, capture_window, capture_display, list_elements.
mac-control-mcp로 무엇을 할 수 있나요?
실행 중인 모든 앱의 Accessibility tree를 읽고 수정할 수 있으며, Safari와 Chrome 제어, 화면 캡처 및 OCR, 클릭 및 타이핑, 윈도우 및 클립보드 관리, Mail, Calendar, Reminders와 같은 Apple 앱 제어가 가능합니다.
mac-control-mcp를 사용하려면 어떤 macOS 버전이 필요한가요?
macOS 14.0 이상이 필요합니다.
mac-control-mcp를 실행하려면 Python이나 Node가 필요한가요?
아니요. 네이티브 Swift 앱 번들이며, npm 패키지는 인증된 앱을 다운로드하는 얇은 런처 역할만 수행합니다.
mac-control-mcp에 어떤 권한이 필요한가요?
첫 번째 도구 호출 시 화면 기록, Accessibility, Apple Events에 대한 macOS 승인 프롬프트가 나타나며, 한 번만 허용하면 됩니다.
mac-control-mcp가 네트워크 호출을 하나요?
아니요. 모든 작업은 로컬 시스템 통합으로 이루어집니다.