Log inSubmit server
Hammerspoon MCP logo

Hammerspoon MCP

Controls macOS windows, apps, media, displays, and Hammerspoon configuration through typed MCP tools.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Hammerspoon MCP

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-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@vukvukovich/hammerspoon-mcp"
      ],
      "env": {
        "HS_MCP_TOOLS": "YOUR_VALUE_HERE"
      }
    }
  }
}

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

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Automated check passed— started and listed 38 tools correctly (6d ago).

Overview

The hammerspoon-mcp MCP server connects MCP clients to a running Hammerspoon process on macOS through the `hs` CLI and `hs.ipc`. It provides typed tools for inspecting and arranging windows, managing applications, controlling audio and displays, switching Spaces, and working with Hammerspoon configuration. Use it when an agent needs local Mac automation or a feedback loop for editing, reloading, and debugging `init.lua`. Arbitrary Lua, AppleScript, and guarded UI presses require the `HS_MCP_TOOLS=all` setting.

Use cases

  • Arrange application windows across macOS screens
  • Switch audio devices and control media playback
  • Inspect Hammerspoon APIs and console errors
  • Reload and debug a Hammerspoon configuration
  • Move between macOS Spaces

Key features

  • Typed MCP tools for macOS window and application control
  • Hammerspoon API search and console access
  • Screen, Space, audio, brightness, and media controls
  • Safe default tier with optional gated tools
  • Static Lua tool bodies with encoded arguments

Tools38

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

Verified live~4.8k 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.

5/5 checks healthy over the last 46d

What it can do

From the 38 tools this server returned when we ran it; 16 declare their own safety hints.

Makes network requests · 3Read-only tools · 38
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceSigned build
Package age67 days
Maintainers1

Observed 2026-10-18 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 8d ago via OSV.dev · @vukvukovich/hammerspoon-mcp (npm)

Adoption & maintenance

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

GitHub stars1Stargazers on the source repository.
npm downloads204Package downloads in the last 30 days.
Last commit25d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed38Callable tools this server registers over MCP.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Hammerspoon MCP works

What hammerspoon-mcp MCP server does

The hammerspoon-mcp MCP server exposes macOS automation through Hammerspoon as MCP tools. It can inspect running applications and windows, focus or launch apps, move and resize windows, apply named layouts, and report connected screens. It also provides controls for Spaces, display brightness, audio devices, volume, mute, and system media keys.

For Hammerspoon development, the server can search the bundled API reference, read recent console output, reload ~/.hammerspoon/init.lua, and display a temporary notification. A health check reports the resolved hs executable, whether Hammerspoon responds, and its version.

How it works

MCP requests are translated into Lua programs executed by the running Hammerspoon process. Communication uses the Hammerspoon command-line interface and its hs.ipc module. The server communicates through a persistent Unix socket when available and can fall back to launching hs with an argument array; it does not use a shell to parse commands.

Tool arguments are validated, encoded as JSON, and then base64-encoded before being passed to a fixed Lua prelude. The Lua bodies are static rather than assembled from interpolated user input. This design keeps ordinary tool calls separate from the Lua source they execute.

The default tool tier is intended for reading, inspecting, arranging, and other controlled actions. hs_eval, hs_applescript, and hs_ui_press are disabled unless HS_MCP_TOOLS=all is configured. The UI tool requires an expected label or role from inspection and rejects the action if the element has changed.

Setup and configuration

The hammerspoon-mcp MCP server requires macOS, Node.js 24 or newer, and an installed, running Hammerspoon application. Add require("hs.ipc") to ~/.hammerspoon/init.lua, reload the Hammerspoon configuration, and verify the bridge with hs -c "return 1 + 1". A result of 2 confirms that the command-line bridge is responding.

Install the server for a client that accepts an MCP server command with npx -y @vukvukovich/hammerspoon-mcp. For Claude Code, the documented command is claude mcp add hammerspoon -- npx -y @vukvukovich/hammerspoon-mcp. The optional HS_MCP_TOOLS=all environment variable enables the three gated tools.

Tools and capabilities

Available capabilities include:

  • Check bridge health, search Hammerspoon API documentation, tail the console, reload configuration, and show notifications.
  • List, focus, move, resize, and arrange windows using IDs, title matches, pixel coordinates, or named layout presets.
  • List, launch, and focus applications, including bundle IDs, PIDs, and window counts.
  • Inspect screens, Spaces, machine status, audio devices, and current display state.
  • Switch Spaces, change audio input or output devices, set volume or mute, adjust built-in display brightness, and control media playback.
  • With the optional tool tier, evaluate Lua, run AppleScript against supported macOS applications, and press inspected UI elements.

Tool names and argument shapes may change because the project is pre-1.0.

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 MCP

hammerspoon-mcp is an MCP server that connects AI clients to a running Hammerspoon process on macOS through `hs.ipc`. Its main tools inspect and arrange windows, manage applications, control audio and displays, search Hammerspoon’s API, tail the console, and reload `init.lua`; optional tools evaluate Lua, run AppleScript, or press inspected UI elements.

Install it through an MCP client using `npx -y @vukvukovich/hammerspoon-mcp`. Before connecting, install and run Hammerspoon, load `require("hs.ipc")` in `~/.hammerspoon/init.lua`, reload the configuration, and verify that `hs -c "return 1 + 1"` returns `2`.

Yes, hammerspoon-mcp works with Claude Desktop through its standard `mcpServers` configuration. Add a server named `hammerspoon` with `command` set to `npx` and `args` set to `["-y", "@vukvukovich/hammerspoon-mcp"]`, then ensure Hammerspoon and its `hs.ipc` module are running.

Set `HS_MCP_TOOLS=all` in the MCP server environment. This enables `hs_eval`, `hs_applescript`, and `hs_ui_press`; they are not available in the default tool tier. The UI press tool also requires an expected label or role from a prior inspection.

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 MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/hammerspoon-mcp?style=directory)](https://allmcps.com/mcp/hammerspoon-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/hammerspoon-mcp"><img src="https://allmcps.com/api/badge/hammerspoon-mcp?style=directory" alt="Hammerspoon MCP on AllMCPs" /></a>