MCP.Market

Hammerspoon MCP server

by mobabur94·io.github.mobabur94/hammerspoon·v0.1.0·1 stars
No reviews yet

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

C62/100grade C
Write a reviewInstall
What users say
No reviews yet
Be the first
Safety scan
C62/100

full report

Adoption
New

1 stars22 downloads/wk

Reviews

Write one

Nobody has reviewed Hammerspoon yet.

If you have run it, two minutes of your experience saves the next person an afternoon.

Hammerspoon tools (75, 9 write)

write = sends, deletes, buys or posts

Read from the package source without running it. The installed server may list more.

  • hs_alert

    Show a large on-screen alert message (HUD-style overlay that auto-dismisses).

  • hs_audio_datasources

    List available data sources for a device (e.g., 'Internal Speakers' vs 'Headphones' on the same device). Can also set the active source.

  • hs_audio_default

    Get or set the default audio device. When setting, matches by name substring (case-insensitive).

  • hs_audio_devices

    List all audio devices (input + output). Shows name, UID, type, volume, mute state, and whether it's the current default.

  • hs_audio_mute

    Get or toggle mute for a specific device or the default output.

  • hs_audio_volume

    Get or set volume for a specific device (by name substring) or the default output. Volume is 0-100.

  • hs_audio_watch

    Start watching audio device changes (device added/removed, default changed, volume changed). Events appear as updates to resource `watcher://audio`.

  • hs_battery

    Get battery status.

  • hs_bluetooth_connect

    Connect to a paired Bluetooth device by name or MAC address.

  • hs_bluetooth_devices

    List paired Bluetooth devices with connection status. Use `connected: true` to filter to only connected devices.

  • hs_bluetooth_disconnect

    Disconnect a Bluetooth device by name or MAC address.

  • hs_bluetooth_power

    Turn Bluetooth on or off.

  • hs_bluetooth_status

    Get Bluetooth power state and discoverability.

  • hs_brightness

    Get or set display brightness (0-100).

  • hs_caffeinate

    Prevent the Mac from sleeping for a duration. Like the `caffeinate` command but manageable.

  • hs_click

    Click at screen coordinates.

  • hs_clipboard

    Read or write the system clipboard.

  • hs_dark_mode

    Get or toggle macOS dark mode.

  • hs_evalwrite action

    Execute arbitrary Lua code in the Hammerspoon runtime. Returns the string result. Use for anything not covered by other tools.

  • hs_executewrite action

    Run a shell command and return its output. Uses hs.execute which runs in the user's environment.

  • hs_finder_open

    Open a path in Finder (file or folder). Reveals in Finder if it's a file.

  • hs_finder_selection

    Get the currently selected files/folders in Finder.

  • hs_focus_cancel_timerwrite action

    Cancel a scheduled Focus mode timer (from hs_focus_schedule) without disabling DND.

  • hs_focus_install_shortcutwrite action

    Creates helper Shortcuts for Focus mode control. Opens the Shortcuts app with instructions. You need to manually create: 1. "Enable DND" shortcut: Set Focus → Do Not Disturb → Turn On 2. "Disable DND" shortcut: Set Focus → Do Not Disturb → Turn Off 3. "Toggle Focus" shortcut: Set Focus → Do Not Disturb → Toggle This only needs to be done once.

  • hs_focus_schedule

    Enable DND for a specified duration, then automatically disable it. Uses hs.timer.

  • hs_focus_shortcut

    Enable or disable Focus/DND using macOS Shortcuts app. Requires a shortcut named "Toggle Focus" to be installed. Use hs_focus_install_shortcut first if you haven't set one up. This is the most reliable method on macOS 13+.

  • hs_focus_status

    Get the current Do Not Disturb / Focus mode status. Returns whether DND is active and the active focus profile name if available.

  • hs_focus_toggle

    Toggle Do Not Disturb on/off via Control Center. Brief visual flash of Control Center is unavoidable.

  • hs_focus_window

    Focus a window by its ID or by title substring match.

  • hs_get_clipboard_history

    Read the full clipboard history buffer. Returns array of {text, timestamp, app}. Requires `hs_watch_clipboard_history` to be running.

  • hs_hotkey

    Press a key combination. Examples: "cmd+c", "cmd+shift+4", "return", "escape".

  • hs_kill_appwrite action

    Quit an application by name.

  • hs_launch_app

    Launch or activate an application by name.

  • hs_list_apps

    List running applications.

  • hs_list_layouts

    List all saved window layout names.

  • hs_list_watchers

    List all active watchers.

  • hs_list_windows

    List all visible windows. Returns array of {id, app, title, frame: {x,y,w,h}, isMinimized}.

  • hs_mouse_position

    Get current mouse cursor position.

  • hs_move_window

    Move and/or resize a window by ID.

  • hs_notifywrite action

    Post a macOS notification.

  • hs_open_url

    Open a URL in the default browser or a specific app.

  • hs_quicklook

    Show a Quick Look preview of a file (press Space equivalent).

  • hs_restore_layout

    Restore a previously saved window layout by name. Windows are matched by app name + title.

  • hs_save_layout

    Save the current window positions as a named layout. Can be restored later with hs_restore_layout.

  • hs_screens

    Get info about connected displays.

  • hs_screenshot

    Take a screenshot. Returns base64 PNG.

  • hs_spaces_active

    Get the currently focused space ID and which screen it's on.

  • hs_spaces_addwrite action

    Create a new space on the specified screen (or main screen). Briefly flashes Mission Control.

  • hs_spaces_goto

    Switch to a specific space by ID or by index (1-based position on the main screen). Note: briefly flashes Mission Control.

  • hs_spaces_list

    List all Spaces across all screens. Returns per-screen arrays of space IDs with the active space marked. Also shows which windows are on each space.

  • hs_spaces_mission_control

    Toggle Mission Control, App Exposé, Launchpad, or Show Desktop.

  • hs_spaces_move_window

    Move a window to a different space. The window stays focused but appears on the target space.

  • hs_spaces_removewrite action

    Remove a space by ID. Cannot remove the active space or the last remaining space. Briefly flashes Mission Control.

  • hs_spaces_window_spaces

    Show which space(s) a window is on (some windows appear on all spaces).

  • hs_spaces_windows

    List all windows on a specific space.

  • hs_system_info

    Get detailed system information: hostname, OS version, CPU, memory, uptime, thermal state.

  • hs_timer_cancelwrite action

    Cancel a running timer by name.

  • hs_timer_list

    List all active timers.

  • hs_timer_start

    Start a named countdown timer. Shows a notification and emits an event when it fires. Useful for pomodoro, reminders, etc.

  • hs_trash

    Move a file or folder to Trash (reversible delete).

  • hs_type

    Type text at current cursor position.

  • hs_unwatch

    Stop a watcher by its ID.

  • hs_volume

    Get or set system volume (0-100).

  • hs_watch_apps

    Start watching application lifecycle events (activated, deactivated, launched, terminated, hidden, unhidden). Events appear as updates to resource `watcher://apps`.

  • hs_watch_battery

    Start watching battery status changes (charge level, power source). Events appear as updates to resource `watcher://battery`.

  • hs_watch_clipboard

    Start watching pasteboard (clipboard) changes. Fires on every copy. Events appear as updates to resource `watcher://clipboard`.

  • hs_watch_clipboard_history

    Start a clipboard history tracker. Maintains a ring buffer of recent clipboard entries (text, timestamp, source app). Events appear as updates to resource `watcher://clipboard_history`. Use `hs_get_clipboard_history` to read the full buffer.

  • hs_watch_paths

    Start watching filesystem paths for changes. Events appear as updates to resource `watcher://paths`.

  • hs_watch_screens

    Start watching display configuration changes (monitors connected/disconnected/reconfigured). Events appear as updates to resource `watcher://screens`.

  • hs_watch_sleep

    Start watching system sleep/wake/lock/unlock events. Events appear as updates to resource `watcher://sleep`.

  • hs_watch_urls

    Start watching URL events. Captures: (1) hammerspoon://mcp/... custom scheme URLs opened from other apps, (2) HTTP callback URLs if Hammerspoon is set as default browser. Events appear as updates to resource `watcher://urls`. Use this to let external apps trigger your agent via URLs.

  • hs_watch_usb

    Start watching USB device connect/disconnect events. Events appear as updates to resource `watcher://usb`.

  • hs_watch_wifi

    Start watching WiFi network changes. Events appear as updates to resource `watcher://wifi`.

  • hs_wifi

    Get current WiFi info.

  • hs_window_layout

    Apply a window layout preset. Presets: • "left-half" / "right-half" / "top-half" / "bottom-half" — snap focused window • "maximize" — fill screen (not fullscreen mode) • "center" — center at 70% screen size • "thirds-left" / "thirds-center" / "thirds-right" — vertical thirds • "quarters-tl" / "quarters-tr" / "quarters-bl" / "quarters-br" — quadrants • "cascade" — cascade all visible windows • "sid

Public scan report

scanner v0.1.9 · 2026-09-23 · same rubric, same numbers if you re-run it

1 high1 medium
  • Code scan21 source files scanned8/25
  • –Live reliabilityno gateway calls yet and no remote to proben/a
  • –Tool poisoningtools not inspected (local package is not executed); not countedn/a
  • Auth qualitylocal package, no credentials required12/15
  • Maintenancelast push 47 days ago12/15
  • Maintainer identityregistry namespace matches repository owner; GitHub account older than a year8/10

Findings (2)

  • mediumeval / new Function usedexec.eval
    dist/audio-tools.js: …t per-device) return bridge.eval(` if _mcpAudioWatcher then _mcpA…
  • highShell command built from a string (injection risk)exec.shell-concat
    dist/bridge.js: … try { const result = execSync(`${this.hsPath} -c '${escaped}'`, { timeout: t…
Overall 62/100. Components that don't apply are left out of the denominator. Any critical finding is an F.RubricAppeal a findingJSON

How Hammerspoon compares

Against every graded Media MCP server, from our own scans and uptime checks. Updated after each scan run.

Safety score
62/100
higher than 16% of 1,337 Media servers
Tools
75
the typical Media server has 7
Tools that change things
12%
typical: 4%. Fewer write tools means less an agent can break
GitHub stars
1
more than 55% of 715 Media servers
Downloads a week
22
more than 9% of 365 Media servers with a package

What its tools let an agent do: 66 read · 9 change

Install Hammerspoon in Claude Code, Cursor or VS Code

Runs npx -y hammerspoon-mcp on your machine. Read the scan report first; the gateway never runs local packages.

claude mcp add hammerspoon -- npx -y hammerspoon-mcp
Add to Cursor

What the publisher says

From the Hammerspoon repository's README, as published. We do not edit it. Read it on GitHub

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/claudedesktopconfig.json:

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

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

Kiro

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

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

Tools

🪟 Window Management (7)

Shortened. The full README is on GitHub.

Nothing above is checked by us. What we check is on the safety report.

Hammerspoon: common questions

Is Hammerspoon MCP server safe?
With care: it is graded C, so read the findings first (62/100). Read the Hammerspoon safety report
How do I install Hammerspoon?
It runs on your machine. Copy the Claude Code, Cursor, VS Code or Claude Desktop config from the install section.
Does Hammerspoon need an API key?
Not as far as the registry entry and our scan can tell: no credentials are declared or required.
Is Hammerspoon maintained?
The last commit was 88 days ago (2026-08-08). The latest release is v0.1.0.
What can I use instead of Hammerspoon?
Servers from other publishers that do the same job: Macos MCP server, FunASR MCP server and FFmpeg MCP server.
How does Hammerspoon compare with other Media MCP servers?
safety score 62/100 (higher than 16% of 1,337 Media servers); tools 75 (the typical Media server has 7); tools that change things 12% (typical: 4%. Fewer write tools means less an agent can break). Full comparison.

Alternatives to Hammerspoon

Same job from other publishers: the closest match first, then the best rated.

  • Macos
    Control macOS settings, apps, windows, audio, Music, displays, screenshots, and Focus mode via MCP.
    A
  • FunASR
    Transcribe local audio with FunASR and SenseVoice using private, on-device inference.
    A
  • FFmpeg
    Trim, convert, resize, compress, and remix audio and video.
    A
  • Audio
    Edit, analyze and convert audio: loudness, spec checks, denoise, EQ, cuts, BPM, key. No ffmpeg.
    A
  • Transloadit Media Processing
    Process video, audio, images and documents with Transloadit Robots. Connect by URL with OAuth.
    A