Log inSubmit server
Hammerspoon logo

Hammerspoon

Control macOS windows, Spaces, audio, Bluetooth, apps, input, and system state through Hammerspoon and MCP.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Hammerspoon

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "hammerspoon": {
      "command": "npx",
      "args": [
        "-y",
        "hammerspoon-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command didn't complete successfully in our automated test.

npx -y hammerspoon-mcp

ersion of npm available! 10.1.0 -> 12.2.1 npm notice Changelog: <https://github.com/npm/cli/releases/tag/v12.2.1> npm notice Run `npm install -g npm@12.2.1` to update! npm notice npm ERR! code EBADPLATFORM npm ERR! notsup Unsupported platform for hammerspoon-mcp@0.1.0: wanted {"os":"darwin"} (current: {"os":"linux"}) npm ERR! notsup Valid os: darwin npm ERR! notsup Actual os: linux npm ERR! A complete log of this run can be found in: /home/user/.npm/_logs/2026-10-22T12_04_03_185Z-debug-0.log

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 2d ago.

Overview

The hammerspoon MCP server connects MCP clients to Hammerspoon for programmatic macOS automation, including windows, Spaces, audio, Bluetooth, Focus mode, and system state. It runs as a Node.js stdio server and sends requests through the Hammerspoon `hs` command-line interface, while named-pipe watchers provide OS event streams. Reach for it when an agent needs direct macOS control rather than screenshot-based clicking. It requires macOS 13+, Node 22+, Hammerspoon, and additional setup for Bluetooth control.

Use cases

  • Arrange application windows into saved layouts
  • Switch audio devices and control volume
  • Move windows between macOS Spaces
  • Monitor clipboard, display, network, and USB events
  • Launch applications and send keyboard input

Key features

  • Window management and saved layouts
  • Spaces and virtual desktop control
  • Audio, Bluetooth, and Focus controls
  • Application, input, and screenshot automation
  • System state, Finder, and clipboard tools
  • Live macOS event watchers

Tools75

What Hammerspoon lets your agent do. Expand a tool for its parameters.

Self-reported~888 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 13d ago via OSV.dev · hammerspoon-mcp (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars2Stargazers on the source repository.
npm downloads83Package downloads in the last 30 days.
Last commit2mo agoMost recent push to the default branch.
Install checkInconclusiveInstall command did not finish in our automated test.
Tools exposed75Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Hammerspoon works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Hammerspoon

hammerspoon is an MCP server that connects AI agents to Hammerspoon on macOS. Its main tools manage windows and Spaces, control applications and input, switch audio and Bluetooth devices, inspect system state, operate Finder, and subscribe to events such as clipboard, Wi-Fi, USB, battery, and sleep changes.

Install Hammerspoon and Node 22 or later, enable `hs.ipc` in `~/.hammerspoon/init.lua`, reload Hammerspoon, and run `npx hammerspoon-mcp`. The server searches standard locations and the Hammerspoon application bundle for the `hs` executable.

Yes, hammerspoon works with Claude Desktop through a stdio configuration. Add an MCP server named `hammerspoon` with `npx` as the command and `hammerspoon-mcp` as its argument in Claude Desktop’s configuration file.

Install `blueutil` with `brew install blueutil` before using the Bluetooth tools. The server uses that utility for Bluetooth power, device listing, connection, and disconnection operations.

Yes, hammerspoon can monitor several macOS event categories through watcher tools. Supported examples include applications, Wi-Fi, USB devices, battery state, screens, filesystem paths, sleep and wake, clipboard changes, and incoming Hammerspoon URLs.

Related MCP servers

All in OS Automation All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewHammerspoon AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/hammerspoon?style=directory)](https://allmcps.com/mcp/hammerspoon)
HTML Embed
<a href="https://allmcps.com/mcp/hammerspoon"><img src="https://allmcps.com/api/badge/hammerspoon?style=directory" alt="Hammerspoon on AllMCPs" /></a>