hammerspoon

hammerspoon-mcp

1 つの MCP サーバーを通じて、AI エージェントが macOS を深く制御できるようにします。ウィンドウ、オーディオ、Bluetooth、Spaces、集中モード、200 以上の OS API に対応します。

これは何ですか？

MCP サーバーとして、AI エージェントと、利用可能な macOS 自動化ツールの中でも最も強力な Hammerspoon を連携させます。スクリーンショットを撮ってクリックするツールとは異なり、エージェントはプログラムから OS レベルでアクセスできます。ID でウィンドウを管理したり、名前でオーディオデバイスを切り替えたり、アプリを Spaces 間で移動したり、集中モードを切り替えたり、リアルタイムの OS イベントを購読したりできます。

75 個のツール。購読可能なリソース 12 個。ネイティブ依存関係はゼロです。

クイックスタート

# 1. Install Hammerspoon (if you haven't)
brew install --cask hammerspoon

# 2. Enable the IPC module (one-time setup)
#    Add this line to ~/.hammerspoon/init.lua:
#    require("hs.ipc")
#    Then reload your Hammerspoon config (Cmd+Alt+Ctrl+R or restart the app)

# 3. (Optional) Install the hs CLI symlink for convenience:
#    Run in Hammerspoon console: hs.ipc.cliInstall()
#    Or manually: ln -sf /Applications/Hammerspoon.app/Contents/Frameworks/hs/hs ~/.local/bin/hs

# 4. Run the MCP server
npx hammerspoon-mcp

注： サーバーは hs バイナリを自動検出します。~/.local/bin/hs、/usr/local/bin/hs、/opt/homebrew/bin/hs、およびアプリバンドルのパスを確認します。Hammerspoon が /Applications にインストールされていれば、hs を PATH に追加する必要はありません。

アーキテクチャ

┌─────────────────────────────────────────────────────────┐
│  MCP Client (Claude, Cursor, MeshClaw, etc.)            │
└──────────────────────────┬──────────────────────────────┘
                           │ stdio (JSON-RPC)
┌──────────────────────────▼──────────────────────────────┐
│  hammerspoon-mcp (Node.js)                              │
│  ├─ tools → execSync("hs -c '...'")  (request/response)│
│  └─ watchers → named pipe reader     (push events)     │
└──────────────────────────┬──────────────────────────────┘
                           │ hs CLI / named pipe
┌──────────────────────────▼──────────────────────────────┐
│  Hammerspoon.app (Lua runtime + ObjC bridge)            │
│  200+ modules: window, screen, spaces, audio, wifi,     │
│  bluetooth, battery, USB, filesystem, accessibility...  │
└──────────────────────────┬──────────────────────────────┘
                           │
              macOS APIs (CoreGraphics, IOKit, etc.)

MCP クライアントの設定

{
  "mcpServers": {
    "hammerspoon": {
      "command": "npx",
      "args": ["hammerspoon-mcp"]
    }
  }
}

claude mcp add hammerspoon -- npx hammerspoon-mcp

{
  "servers": {
    "hammerspoon": {
      "command": "npx",
      "args": ["hammerspoon-mcp"]
    }
  }
}

{
  "mcpServers": {
    "hammerspoon": {
      "command": "npx",
      "args": ["hammerspoon-mcp"]
    }
  }
}

ツール

🪟 ウィンドウ管理（7）

🖥️ Spaces／仮想デスクトップ（9）

📱 アプリケーション制御（3）

⌨️ 入力（3）

🖼️ 画面（3）

🔊 オーディオデバイス（6）

🔵 Bluetooth（5）

blueutil が必要です：brew install blueutil

🌙 集中モード／おやすみモード（6）

🔋 システム状態（6）

🔆 ディスプレイ（1）

⏱️ タイマー（3）

📁 Finder／ファイル（4）

🛠️ ユーティリティ（5）

👁️ ウォッチャー — OS イベントのライブストリーム（13）

🧪 エスケープハッチ（1）

これにより、専用ツールでは扱われていない 200 以上の Hammerspoon モジュールすべてにアクセスできます。USB の詳細、シリアルポート、ネットワークインターフェース、Canvas 描画、メニューバー項目などが含まれます。

リソース（サブスクリプション）

MCP クライアントはリソース URI をサブスクライブし、OS イベントの発生時にプッシュ通知を受け取れます。

イベントストリーミングの仕組み

Agent calls: hs_watch_wifi
  → Server injects Lua watcher into Hammerspoon runtime
  → macOS WiFi change fires
  → Watcher writes JSON to named pipe (/tmp/hs-mcp-events.pipe)
  → Node reader emits event
  → Server calls sendResourceUpdated("watcher://wifi")
  → Client reads resource → gets { ssid: "NewNetwork", ... }

使用例

「エディターとターミナルを左右に並べて」

hs_window_layout({ preset: "side-by-side" })

「オーディオを AirPods に切り替えて」

hs_audio_default({ output: "airpods" })
→ "set default output: AirPods Pro"

「Slack を Space 3 に移動して」

hs_list_windows({ app: "Slack" })  → { id: 4523, ... }
hs_spaces_move_window({ windowId: 4523, spaceIndex: 3 })

「25 分の集中セッションを開始して」

hs_focus_schedule({ minutes: 25 })
hs_timer_start({ name: "pomodoro", minutes: 25, message: "Break time!" })

「IDE から切り替えたときに通知して」

hs_watch_apps()
→ Events stream to watcher://apps whenever focus changes

「ヘッドフォンを接続して音量を 40% に設定して」

hs_bluetooth_connect({ device: "WH-1000XM5" })
hs_audio_volume({ device: "WH-1000XM5", volume: 40 })

他の選択肢との比較

前提条件

hs CLI のシンボリックリンク（hs.ipc.cliInstall()）は任意です。サーバーは Hammerspoon アプリバンドル内のバイナリを自動検出します。

セットアップの確認

# If hs is on your PATH:
hs -c 'return "ok"'

# Or directly via the app bundle:
/Applications/Hammerspoon.app/Contents/Frameworks/hs/hs -c 'return "ok"'

# Should print: ok

これが動作すれば、npx hammerspoon-mcp は正常に接続できます。

アクセス許可

プロジェクト構成

hammerspoon-mcp/
├── src/
│   ├── index.ts              MCP server entry point + resource registration
│   ├── bridge.ts             hs CLI bridge (auto-discovers binary, eval, evalJson)
│   ├── tools.ts              Core tools: window, app, input, screen, system, eval (23)
│   ├── watcher-tools.ts      Watcher management tools (13)
│   ├── watchers.ts           Named pipe event bridge
│   ├── spaces-tools.ts       Spaces / virtual desktop tools (9)
│   ├── audio-tools.ts        Audio device management (6)
│   ├── focus-tools.ts        DND / Focus mode (6)
│   ├── bluetooth-tools.ts    Bluetooth via blueutil (5)
│   └── extra-tools.ts        Brightness, timers, system info, Finder, utils (13)
├── package.json
├── tsconfig.json
├── LICENSE                   MIT
└── README.md

開発

git clone <repo>
cd hammerspoon-mcp
npm install
npm run dev     # Run with tsx (hot reload)
npm run build   # Compile to dist/
npm start       # Run compiled version

仕組み

1. 起動 — ブリッジは hs バイナリを自動検出し（~/.local/bin、/usr/local/bin、/opt/homebrew/bin、アプリバンドルを確認）、接続を検証します
2. ツールは hs -c '<lua>' を使って同期的に実行されます。通常、呼び出しごとに 30～80ms かかります。標準出力のノイズ（-- Loading extension: ...）は自動的に除去されます
3. ウォッチャーは JSON 行を FIFO パイプに書き込む Lua コードを注入します。Node のリーダープロセスがそれらを MCP リソース更新として送信します
4. リソースはウォッチャーごとに直近 50 件のイベントをバッファリングします。クライアントは更新通知を受け取った後、必要に応じて読み取ります
5. 正常なシャットダウンでは、すべてのウォッチャーを停止し、SIGINT／SIGTERM 時にパイプをクリーンアップします

既知の制限事項

• engines では Node.js 22+ が指定されていますが、サーバーは Node 20 でも問題なくビルドおよび実行できます（テスト済み）
• hs_spaces_goto、addSpaceToScreen、removeSpace は Mission Control を一瞬表示します（macOS の制限です。「視差効果を減らす」を有効にすると最小限に抑えられます）
• Bluetooth ツールには blueutil が必要です（brew install blueutil）
• 集中モード／DND の読み取りにはヒューリスティックを使用します（公開された Apple API が存在しません）
• hs_screenshot は base64 を返すため、全画面キャプチャではサイズが大きくなります
• 保存されたレイアウトは Hammerspoon の実行中のみ保持されます（HS の再読み込みで失われます）
• 名前付きパイプのパスは /tmp/hs-mcp-events.pipe です。同時に実行できるサーバーインスタンスは 1 つだけです

License

MIT © 2026 Mohammed Babur