Control macOS through Hammerspoon: windows, apps, and API search. Injection-safe by design.
Connect Runs on your machine
claude mcp add hammerspoon-mcp -e HS_MCP_TOOLS=<HS_MCP_TOOLS> -e HS_MCP_TRANSPORT=<HS_MCP_TRANSPORT> -e HS_MCP_HS_PATH=<HS_MCP_HS_PATH> -e HS_MCP_DOCS_PATH=<HS_MCP_DOCS_PATH> -e HS_MCP_LOG_LEVEL=<HS_MCP_LOG_LEVEL> -- npx -y @vukvukovich/[email protected]{
"mcpServers": {
"hammerspoon-mcp": {
"command": "npx",
"args": [
"-y",
"@vukvukovich/[email protected]"
],
"env": {
"HS_MCP_TOOLS": "<HS_MCP_TOOLS>",
"HS_MCP_TRANSPORT": "<HS_MCP_TRANSPORT>",
"HS_MCP_HS_PATH": "<HS_MCP_HS_PATH>",
"HS_MCP_DOCS_PATH": "<HS_MCP_DOCS_PATH>",
"HS_MCP_LOG_LEVEL": "<HS_MCP_LOG_LEVEL>"
}
}
}
}{
"mcpServers": {
"hammerspoon-mcp": {
"command": "npx",
"args": [
"-y",
"@vukvukovich/[email protected]"
],
"env": {
"HS_MCP_TOOLS": "<HS_MCP_TOOLS>",
"HS_MCP_TRANSPORT": "<HS_MCP_TRANSPORT>",
"HS_MCP_HS_PATH": "<HS_MCP_HS_PATH>",
"HS_MCP_DOCS_PATH": "<HS_MCP_DOCS_PATH>",
"HS_MCP_LOG_LEVEL": "<HS_MCP_LOG_LEVEL>"
}
}
}
}{
"servers": {
"hammerspoon-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@vukvukovich/[email protected]"
],
"env": {
"HS_MCP_TOOLS": "<HS_MCP_TOOLS>",
"HS_MCP_TRANSPORT": "<HS_MCP_TRANSPORT>",
"HS_MCP_HS_PATH": "<HS_MCP_HS_PATH>",
"HS_MCP_DOCS_PATH": "<HS_MCP_DOCS_PATH>",
"HS_MCP_LOG_LEVEL": "<HS_MCP_LOG_LEVEL>"
}
}
}
}Replace the values in angle brackets with your own. Keys stay on your machine; we never see them.
Tools
This server runs locally, so its tools are listed by your MCP client once it starts.
Environment variables
| Name | Description |
|---|---|
HS_MCP_TOOLSOptional | Which tools to expose. "safe" (default) exposes inspection, window management, and system tools only. "all" additionally exposes hs_eval, hs_applescript, and hs_ui_press, which run arbitrary Lua and AppleScript and press UI elements - anything the user can do. |
HS_MCP_TRANSPORTOptional | How Lua reaches Hammerspoon. "socket" (default) keeps one persistent Unix domain socket, self-installed on first call, with automatic fallback to spawning; "spawn" runs one hs process per call. |
HS_MCP_HS_PATHOptional | Explicit path to the Hammerspoon hs command line tool. Only needed when Hammerspoon is installed somewhere unusual. |
HS_MCP_DOCS_PATHOptional | Explicit path to Hammerspoon's bundled docs.json, used by hs_api_search. |
HS_MCP_LOG_LEVELOptional | Log verbosity on stderr: debug, info (default), warn, or error. |
Details
| Package | @vukvukovich/[email protected] (NPM, stdio) |
| First published | 14 Aug 2026 |
| Last updated | 14 Aug 2026 |
| Registry name | io.github.vukvukovich/hammerspoon-mcp |
More search and web servers See all
Listing data from the official MCP registry. Status and tools from NestDaddy's daily check. Browse all MCP servers.