hammerspoon

hammerspoon-mcp

通过一个 MCP 服务，让 AI Agent 深度控制 macOS——窗口、音频、蓝牙、Spaces、专注模式以及 200 多个操作系统 API。

这是什么？

一个将 AI Agent 接入 Hammerspoon 的 MCP 服务——Hammerspoon 是目前功能最强大的 macOS 自动化工具。与截屏并点击的工具不同，它能让 Agent 以编程方式访问操作系统级功能：按 ID 管理窗口、按名称切换音频设备、在 Spaces 之间移动应用、切换专注模式，以及订阅实时操作系统事件。

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）

🔵 蓝牙（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–80 毫秒。标准输出中的噪声（-- Loading extension: ...）会自动剥离
3. 监视器注入 Lua 代码，将 JSON 行写入 FIFO 管道；Node 读取器进程会将其作为 MCP 资源更新发出
4. 资源会为每个监视器缓冲最近的 50 条事件；客户端收到更新通知后按需读取
5. 正常关闭会停止所有监视器，并在收到 SIGINT/SIGTERM 时清理管道

已知限制

• engines 中指定了 Node.js 22+，但服务在 Node 20 上也能正常构建和运行（已测试）
• hs_spaces_goto、addSpaceToScreen、removeSpace 会短暂闪现 Mission Control（macOS 的限制——启用“减少动态效果”可尽量减轻）
• 蓝牙工具需要 blueutil（brew install blueutil）
• 专注／勿扰状态的读取使用启发式方法（Apple 没有提供公开 API）
• hs_screenshot 会返回 base64 数据——全屏截图的数据量较大
• 保存的布局仅在 Hammerspoon 运行时中保留（重新加载 HS 后会丢失）
• 命名管道路径为 /tmp/hs-mcp-events.pipe——同一时间只能运行一个服务实例

License

MIT © 2026 Mohammed Babur