convez.ai
MCP ServerAutomaçãoAvançado
UnpxreTW

Bellhop — Servidor MCP para macOS em Swift

UnpxreTW/Bellhop

Controle macOS via Claude com ferramentas tipadas — sem computer-use, puro Swift

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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/Bellhop

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 2 meses
Versão
v1.0.0
Issues abertas
0
Contribuidores
3

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。
Ver o original no GitHub

Bom para

Relacionados