Bellhop — Servidor MCP para macOS em Swift
UnpxreTW/Bellhop
Controle macOS via Claude com ferramentas tipadas — sem computer-use, puro Swift
Ver no GitHubServidor MCP escrito em Swift que oferece um conjunto de ferramentas com tipo forte e bem definidas para operar o macOS. Diferente de abordagens genéricas, fornece operações específicas de Terminal, janelas e captura de tela através de APIs nativas (Apple Events, Accessibility).
Instalação
npx convez-ai UnpxreTW/Bellhop1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação remota do macOS via Claude no celular
- Abrir Terminal com Remote Control pré-configurado em Mac headless
- Controle de janelas e captura de tela para workflows documentados
- Integração nativa com Claude Desktop/Code sem dependências externas
Veredito

Bellhop é um MCP server bem-arquitetado e purpose-built que fornece operações macOS confiáveis através de typed tools. Excelente para quem precisa automatizar macOS via Claude com garantia de segurança (sem computer-use ou shell genérico), mas exige entendimento de permissões macOS (Accessibility, Screen Recording) e é restrito ao ecossistema Apple.
README
A tradução para o português deste README ainda está na fila.
Bellhop
A Swift MCP server for operating macOS — purpose-built, typed tools.
Bellhop 是用 Swift 寫的 MCP(Model Context Protocol)server,讓 Claude Code、Claude Desktop 等 MCP client 透過具名、強型別的工具操作 macOS。
跟生態裡多數 macOS MCP server 不同,Bellhop 不是 computer-use(截圖 + 點擊),也不是「丟一段 AppleScript 我幫你跑」的通用 runner——它提供一組目的明確、參數有型別的工具。
核心用途
Bellhop 最初是為了一個情境而生:人在手機上,透過 Claude app 的 dispatch 讓 Mac 開一個新的 Terminal session、跑起 claude 並預設啟用 Remote Control,然後直接在手機上接手那個 session。 dispatch 出來的 agent 只要呼叫 terminal_open,就能在 Mac 上開出帶 Remote Control 的 claude 視窗——這是 computer-use(截圖點擊)或沙盒內的 shell 做不到的(它們碰不到 host 的 Terminal)。
它也能當一般的 Terminal 控制 MCP 給任何 MCP client 用。
為什麼
- 具名工具,不是通用 runner:每個工具都有 JSON Schema 定義的參數,client 一 handshake 就知道能做什麼、怎麼呼叫。
- 走 Apple Event,不靠 GUI:透過
osascript對 Terminal.app 發 Apple Event,不走截圖點擊——do script在螢幕鎖定下照樣可達。 - 單一編譯 binary:純 Swift Package、零 Python / Node runtime,MCP client 直接 spawn。
工具
| 工具 | 作用 | 參數 |
|---|---|---|
terminal_open | 開新 Terminal 視窗,可選 cd 進目錄再跑命令,回傳新分頁識別碼 | command、cwd(皆可選;空=乾淨 shell) |
terminal_run | 在指定 window_id 的視窗跑命令;視窗忙碌(有前景程式在跑)就拒跑、不注入 | command、window_id(皆必填) |
terminal_list_windows | 列出開啟中的視窗 id、標題與 busy 狀態 | 無 |
screen_capture | 截圖存檔、回傳路徑(不 inline 圖);預設主螢幕,可選指定 Terminal 視窗 / 區域 / 螢幕 | window_id、region("x,y,w,h")、display、path、format(png/jpg),皆可選 |
window_list | 跨 App 列出視窗:app 名、bundle id、frame、所在螢幕、是否在畫面上;唯讀、零新權限 | app(過濾)、include_offscreen,皆可選 |
window_save_layout | 把當前視窗排列(跨 Space)存成具名快照 | name(必填) |
window_layout_list | 列出已存的 layout 快照 | 無 |
window_focus | 把指定 App 的視窗帶到最前並聚焦(最小化會先展開);需 Accessibility 權限 | app(必填)、window_title(可選) |
window_set_frame | 把視窗搬移/調整到指定 frame(全域左上座標);需 Accessibility 權限 | app、x、y、width、height(必填)、window_title(可選) |
terminal_run 是「把命令打進該視窗當前在跑的程式」,所以只在視窗閒置於 shell 提示字元(busy=false)時乾淨執行——跑著程式的視窗(含其他編輯器 / session)會被自動拒跑、不被誤注入。先用 terminal_list_windows 挑 busy=false 的目標。
screen_capture 跟 terminal 工具不同性質:它走 screencapture、需 macOS Screen Recording 權限、且螢幕鎖定下截不到(不是 lock-safe)。截圖存成檔案、只回路徑(避開 base64 體積),預設存 ~/Downloads/。指定 window_id(取自 terminal_list_windows)會只截那個 Terminal 視窗。
window_* 工具是跨 App 的通用視窗面:window_list 走 CGWindowList 唯讀讀取、不需要任何新權限——但視窗標題只在執行 Bellhop 的 app 已授 Screen Recording 權限時讀得到(幾何與 owner 資訊免權限)。window_save_layout 把快照寫進 ~/Library/Application Support/Bellhop/layouts/<name>.json。
會動視窗的工具(window_focus、window_set_frame)直呼 Accessibility API(AXUIElement)、不走 osascript——需要 macOS Accessibility 權限(掛在 spawn Bellhop 的宿主 app 頭上,未授權時工具會回報引導、不會卡住),且只搆得到當前 Space 的視窗、螢幕鎖定下無作用(不是 lock-safe)。window_set_frame 寫入後會回讀驗收、回報實際落定的 frame(app 可能強制最小尺寸或尺寸級距)。原生排列(window_arrange)與 layout 還原(window_restore_layout)接口已定型、待選單尋址實機驗證後推出,本版尚未曝光。
安裝與使用
到 Releases 下載編譯好的 Bellhop 執行檔。下載後驗證 checksum(每個 release 附 SHA256SUMS):
shasum -a 256 -c SHA256SUMS
下載的執行檔帶 quarantine,Gatekeeper 會擋,先移除:
xattr -dr com.apple.quarantine /path/to/Bellhop
把 Bellhop 註冊進 MCP client。依用途,可能要寫進一或兩個地方(格式相同,command 給執行檔的絕對路徑):
- 本機 Claude Code session →
~/.claude.json頂層mcpServers - Claude app / 手機 dispatch(核心用途) →
~/Library/Application Support/Claude/claude_desktop_config.json的mcpServers
"mcpServers": {
"bellhop": { "command": "/path/to/Bellhop" }
}
Claude Code 用 claude mcp list 應顯示 bellhop ✔ Connected;改完 claude_desktop_config.json 要重啟 Claude Desktop 才生效。
首次使用權限
第一次呼叫工具時要過授權,之後不再問:
- Mac(terminal 工具):跳出「Terminal.app 想要被控制」的 Automation 授權 → 同意。
- Mac(
screen_capture):另需 Screen Recording 權限——到 System Settings → Privacy & Security → Screen Recording 把「執行 Bellhop 的 app」(如 Claude / 終端機)打開,重啟該 app 才生效。未授權時截圖會回could not create image from display。 - 手機端:dispatch 的 session 第一次用這個工具會請你核准權限 → 同意。
執行需求:macOS 14+。
讓開出的 session 帶 Remote Control
核心用途要手機接管 dispatch 開出的 session,得讓那個 claude 一啟動就帶 Remote Control。兩種做法:
- 每次啟動帶 flag(建議):開 session 的命令用
claude --remote-control——只影響這個 session、不動全域設定。dispatch 時讓 agent 呼叫terminal_open執行它即可。 - 全域預設開啟:在
~/.claude/settings.json設{ "remoteControlAtStartup": true }(或 Claude Code 內/config→ 開「Enable Remote Control for all sessions」)——代價是本機手動開的每個claude也都會帶 Remote Control。
設好後,從手機 dispatch「用 terminal_open 開新視窗執行 claude --remote-control」,新 session 就出現在 Claude app 的 session 列表、可直接接管。
前提:用 claude.ai 帳號 /login(Remote Control 不支援 API key)、方案 Pro / Max 以上、Claude Code v2.1.51+。
觸發方式與限制
兩條觸發路徑:
- 本機執行中的 session 直接觸發:Mac 上任何執行中的 Claude Code session(已在
~/.claude.json註冊)可直接呼叫工具——即時、無額外開銷,也能對既有視窗操作(terminal_list_windows看狀態、terminal_run指定window_id)。想避開 dispatch 的負擔就走這條。 - 手機 dispatch:人不在電腦前時從手機開 session。
⚠️ 手機 dispatch 在沙盒環境執行,比本機 session 直接觸發多一層資源開銷。不想要這層開銷時,改從本機執行中的 session 觸發。
⚠️ dispatch 需要 Claude app 正在執行、且 Mac 處於喚醒狀態。剛開機而 app 還沒啟動時 dispatch 不會執行——即使能 SSH 連進去也一樣(dispatch 機制仍需 app 在跑,不是有 shell 就行)。
開發
從原始碼建置:
swift build -c release
# 產物:.build/release/Bellhop
- 工具鏈:Swift 6.2 / Xcode 26。Xcode 26 需 macOS 15.6+——故建置在 macOS 15.6+ 環境,產物部署目標則下探到 macOS 14。
- Lint / format:SwiftStyleKit(SwiftLint + SwiftFormat 打包);
SWIFTSTYLELINT_STRICT=1把 warning 升 error。 - 測試 / CI:
swift test(單元測試在Tests/BellhopKitTests);GitHub Actions 跑 build、測試與 REUSE 授權合規檢查。 - 版本號:build 時由
BellhopVersionPlugin以git describe從 git tag 注入(單一來源=tag);無 tag 退回 commit hash、無 git 環境退回0.0.0-unknown。