# hammerspoon [Health: Active]

**Category:** 🖥️ OS Automation  
**Repository:** https://github.com/mobabur94/hammerspoon-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 83  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/hammerspoon

## Description
macOS automation via Hammerspoon — 75 tools for windows, Spaces, audio, Bluetooth, and more

## Tools
Capabilities this server exposes over MCP:

- **hs_list_windows** — All visible windows with app, title, frame, id
- **hs_focus_window** — Bring window to front by id or title match
- **hs_move_window** — Move/resize window by id
- **hs_window_layout** — 16 presets (halves, thirds, quarters, grid, cascade, center…) + custom fractional layouts
- **hs_save_layout** — Snapshot all window positions as a named layout
- **hs_restore_layout** — Restore a saved layout (matches by app + title)
- **hs_list_layouts** — List saved layout names
- **hs_spaces_list** — All spaces per screen with active markers
- **hs_spaces_active** — Currently focused space + screen
- **hs_spaces_goto** — Switch by ID or index
- **hs_spaces_move_window** — Move window to another space (optionally follow)
- **hs_spaces_add** — Create a new space
- **hs_spaces_remove** — Remove a space (safety checks)
- **hs_spaces_windows** — Windows on a specific space
- **hs_spaces_window_spaces** — Which space(s) a window is on
- **hs_spaces_mission_control** — Toggle Mission Control / Exposé / Launchpad / Show Desktop
- **hs_list_apps** — Running applications with bundle ID, PID, hidden state
- **hs_launch_app** — Launch or activate an app by name
- **hs_kill_app** — Quit an app
- **hs_click** — Click at coordinates with button + modifier options
- **hs_type** — Type text (Unicode, CJK, emoji)
- **hs_hotkey** — Press key combo (e.g. `"cmd+shift+4"`)
- **hs_screenshot** — Capture full screen or region (base64 PNG)
- **hs_screens** — Display info (resolution, name, rotation)
- **hs_mouse_position** — Current cursor coordinates
- **hs_audio_devices** — List all input/output with volume, mute, transport type
- **hs_audio_default** — Get/set default devices (fuzzy name match)
- **hs_audio_volume** — Volume on any specific device (0–100)
- **hs_audio_mute** — Mute/unmute/toggle any device
- **hs_audio_datasources** — List/switch data sources (speakers vs headphones)
- **hs_audio_watch** — Watch for device changes
- **hs_bluetooth_status** — Power state and discoverability
- **hs_bluetooth_power** — On / off / toggle
- **hs_bluetooth_devices** — List paired or connected devices
- **hs_bluetooth_connect** — Connect by name (fuzzy) or MAC address
- **hs_bluetooth_disconnect** — Disconnect a device
- **hs_focus_status** — Check if DND/Focus is active + profile name
- **hs_focus_toggle** — Toggle via Control Center (no setup needed)
- **hs_focus_shortcut** — Enable/disable via macOS Shortcuts (most reliable)
- **hs_focus_install_shortcut** — One-time setup guide
- **hs_focus_schedule** — DND for N minutes with auto-disable
- **hs_focus_cancel_timer** — Cancel scheduled disable
- **hs_battery** — Charge %, power source, time remaining
- **hs_wifi** — Current SSID and interface details
- **hs_volume** — System volume get/set
- **hs_dark_mode** — Get/toggle dark mode
- **hs_notify** — Post a macOS notification
- **hs_clipboard** — Read/write system pasteboard
- **hs_brightness** — Get/set screen brightness (0–100)
- **hs_timer_start** — Named countdown with notification on fire
- **hs_timer_cancel** — Cancel by name
- **hs_timer_list** — List active timers
- **hs_finder_selection** — Get currently selected Finder items
- **hs_finder_open** — Open/reveal path in Finder
- **hs_trash** — Move to Trash (reversible)
- **hs_quicklook** — Quick Look preview
- **hs_system_info** — CPU, memory, thermal state, uptime
- **hs_caffeinate** — Prevent sleep for N minutes
- **hs_execute** — Run shell command (user environment)
- **hs_open_url** — Open URL in browser or specific app
- **hs_alert** — HUD-style on-screen overlay message
- **hs_watch_apps** — App activated, launched, terminated, hidden
- **hs_watch_wifi** — Network changes
- **hs_watch_usb** — Device connect/disconnect
- **hs_watch_battery** — Charge level, power source
- **hs_watch_screens** — Display configuration
- **hs_watch_paths** — Filesystem changes
- **hs_watch_sleep** — Sleep/wake/lock/unlock
- **hs_watch_clipboard** — Every pasteboard change
- **hs_watch_clipboard_history** — Ring buffer with source app tracking
- **hs_get_clipboard_history** — Read the full buffer
- **hs_watch_urls** — Incoming `hammerspoon://mcp/...` URLs
- **hs_unwatch** — Stop a watcher
- **hs_list_watchers** — List active watchers
- **hs_eval** — Execute arbitrary Lua in the Hammerspoon runtime

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What hammerspoon MCP server does

The hammerspoon MCP server exposes Hammerspoon’s macOS automation runtime through MCP tools. It covers window discovery and layout, virtual desktops, application launching and quitting, keyboard and mouse input, screenshots, displays, audio devices, Bluetooth, Focus mode, battery, Wi-Fi, brightness, dark mode, clipboard access, Finder actions, timers, notifications, and system information.

Window tools can identify visible windows by application, title, frame, and ID, then focus, move, resize, save, or restore layouts. Spaces tools report desktops per display, switch between them, move windows, create or remove spaces, and invoke Mission Control-related views. Other tools can launch applications, send hotkeys and Unicode text, capture screenshots as base64 PNG data, control audio devices, and manage system volume.

The server also includes watchers for application, Wi-Fi, USB, battery, display, filesystem, sleep, clipboard, and URL events. Watcher tools can start or stop subscriptions and list active watchers; clipboard history can retain a ring buffer with source-application tracking.

## How it works

An MCP client communicates with the Node.js process over stdio using JSON-RPC. For ordinary requests, the process invokes the `hs` CLI, which passes Lua-based operations into Hammerspoon. Hammerspoon then uses its Lua runtime and Objective-C bridge to interact with macOS APIs. Event watchers use a named pipe to send changes back to the server.

It does not require native Node dependencies. Bluetooth operations use the separate `blueutil` command-line utility, while Focus controls can use Control Center or macOS Shortcuts depending on the operation.

## Setup and configuration

Install Hammerspoon on macOS 13 or later, then enable its IPC module by adding `require("hs.ipc")` to `~/.hammerspoon/init.lua` and reloading the configuration. Run the server with Node 22 or later using `npx hammerspoon-mcp`.

The server searches several common locations for the `hs` executable, including the user-local directory, Homebrew paths, and the Hammerspoon application bundle. Installing the optional `hs` CLI symlink can make command discovery more convenient, but the documentation says it is not required when Hammerspoon is installed in `/Applications`.

Add the command and `hammerspoon-mcp` argument to an MCP client configuration. The README provides configurations for Claude Desktop, Cursor, VS Code, and a command for Claude Code. Bluetooth support additionally requires `brew install blueutil`. Focus shortcut operations may require the one-time shortcut installation flow exposed by the server.

## Limitations and notes

The hammerspoon MCP server is macOS-specific and depends on a running Hammerspoon installation. Its documented platform badge is macOS 13+, and its runtime requirement is Node 22+. Bluetooth features are not self-contained because they depend on `blueutil`.

Some operations can affect the active desktop session, including typing text, sending hotkeys, changing audio devices, moving windows, switching Spaces, writing to the clipboard, running shell commands, and moving files to the Trash. The available tools therefore operate with the permissions and user environment of the local Mac. Focus toggling through Control Center and Focus control through Shortcuts are separate approaches, with the README identifying the shortcut method as the more reliable option.

_Full upstream README: https://allmcps.com/mcp/hammerspoon/readme_