Hammerspoon

hammerspoon-mcp

Give AI agents deep control over macOS — windows, audio, Bluetooth, Spaces, Focus mode, and 200+ OS APIs — through one MCP server.

[macOS 13+] [Node 22+] [MIT License] [TypeScript]

What is this?

An MCP server that bridges AI agents to Hammerspoon — the most powerful macOS automation tool available. Unlike screenshot-and-click tools, this gives agents programmatic OS-level access: manage windows by ID, switch audio devices by name, move apps between Spaces, toggle Focus mode, and subscribe to real-time OS events.

75 tools. 12 subscribable resources. Zero native dependencies.

Quick Start

# 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 servernpx hammerspoon-mcp

Note: The server auto-discovers the hs binary — it checks ~/.local/bin/hs, /usr/local/bin/hs, /opt/homebrew/bin/hs, and the app bundle path. You don't need hs on your PATH if Hammerspoon is installed to /Applications.

Architecture

┌─────────────────────────────────────────────────────────┐│  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 Client Configuration

{  "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"]    }  }}

Tools

🪟 Window Management (7)

🖥️ Spaces / Virtual Desktops (9)

📱 Application Control (3)

⌨️ Input (3)

🖼️ Screen (3)

🔊 Audio Devices (6)

🔵 Bluetooth (5)

Requires blueutil: brew install blueutil

🌙 Focus / Do Not Disturb (6)

🔋 System State (6)

🔆 Display (1)

⏱️ Timers (3)

📁 Finder / Files (4)

🛠️ Utilities (5)

👁️ Watchers — Live OS Event Streams (13)

🧪 Escape Hatch (1)

This gives access to all 200+ Hammerspoon modules not covered by dedicated tools — USB details, serial ports, network interfaces, Canvas drawing, menubar items, etc.

Resources (Subscriptions)

MCP clients can subscribe to resource URIs and receive push notifications when OS events fire:

How event streaming works

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", ... }

Examples

"Tile my editor and terminal side by side"

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

"Switch my audio to AirPods"

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

"Move Slack to Space 3"

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

"Start a 25-minute focus session"

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

"Notify me when I switch away from my IDE"

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

"Connect my headphones and set volume to 40%"

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

Compared to Alternatives

Prerequisites

The hs CLI symlink (hs.ipc.cliInstall()) is optional — the server auto-discovers the binary inside the Hammerspoon app bundle.

Verify setup

# 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

If this works, npx hammerspoon-mcp will connect successfully.

Permissions

Project Structure

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

Development

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

How It Works

1. Startup — the bridge auto-discovers the hs binary (checks ~/.local/bin, /usr/local/bin, /opt/homebrew/bin, app bundle) and validates connectivity
2. Tools execute synchronously via hs -c '<lua>' — typically 30–80ms per call. Stdout noise (-- Loading extension: ...) is stripped automatically
3. Watchers inject Lua code that writes JSON lines to a FIFO pipe; a Node reader process emits them as MCP resource updates
4. Resources buffer the last 50 events per watcher; clients read on-demand after receiving update notifications
5. Graceful shutdown stops all watchers and cleans up the pipe on SIGINT/SIGTERM

Known Limitations

• Node.js 22+ is specified in engines but the server builds and runs fine on Node 20 (tested)
• hs_spaces_goto, addSpaceToScreen, removeSpace briefly flash Mission Control (macOS limitation — enable "Reduce motion" to minimize)
• Bluetooth tools require blueutil (brew install blueutil)
• Focus/DND reading uses heuristics (no public Apple API exists)
• hs_screenshot returns base64 — large for full-screen captures
• Saved layouts persist only in Hammerspoon's runtime (lost on HS reload)
• Named pipe path is /tmp/hs-mcp-events.pipe — only one server instance at a time

License

MIT © 2026 Mohammed Babur