Hammerspoon

hammerspoon-mcp

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

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 server

npx 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

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{

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

</details>

Claude Code

claude mcp add hammerspoon -- npx hammerspoon-mcp

Cursor / VS Code / Copilot

Add to .vscode/mcp.json:

{

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

</details>

Kiro

Add to ~/.aws/amazonq/mcp.json:

{

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

</details>

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

| Hammerspoon