Spacepal MCP Server

Claude, Cursor ve diğer MCP istemcilerinin Spacepal uygulaması üzerinden macOS Spaces ile çalışmasını sağlar: uygulamaları ve notlarıyla birlikte Spaces’leri listeler, geçiş yapar, yeniden adlandırır, öndeki pencereyi taşır, profilleri uygular, pencere düzenlerini kaydeder ve geri yükler. Yerel, stdio, ağ çağrısı yapmaz.

Dokümantasyon

Spacepal MCP server

Lets Claude, Cursor and other MCP clients work with your macOS Spaces through Spacepal: "switch to my Mail Space", "what's on Desktop 3?", "name this desktop Research".

An agent lists Spaces, switches to Research and names a desktop through the Spacepal MCP server (illustration)

It runs locally over stdio. It reads the Space list Spacepal writes to ~/Library/Application Support/Spacepal/state.json and sends commands through the spacepal:// URL scheme. It makes no network calls.

Several Claude Code sessions

If you run Claude Code on several Spaces, Spacepal 1.2.12 and later marks the Space whose session is waiting for you (a permission request or a question) or has finished, and agent_sessions lets an agent see the same thing, for example to check whether the backend session is done. Turn it on in Spacepal: Settings > General > Claude Code > Add to Claude Code. list_spaces also shows each project's git branch, changed files and local dev servers.

The Spacepal overview: two Spaces marked Waiting and one Done, with git branches and localhost servers (demo mode)

More: Spacepal for Claude Code

Requirements

  • macOS 14 or later, with Spacepal running (direct or Mac App Store build). Download Spacepal: 14-day free trial, no account; names, notes and switching stay free after it.
  • Node.js 18 or later

Tools

ToolWhat it does
list_spacesEvery Space with its number, name, display, apps, note, and which one is active
current_spaceThe Space you are on
switch_spaceSwitch by number or name, or step with next, previous, back
move_window_to_spaceSend the frontmost window to a Space by number or name, or to next or previous
open_urlOpen a link in a new browser window on a chosen Space, or on the project's own Space by default, so it does not land in a browser window on another Space
agent_sessionsThe Claude Code sessions by Space: which one is waiting for the user (and why), which finished, and since when
new_project_spaceMake a named Space for a project folder and start Claude Code there (direct version of Spacepal)
rename_spaceName a Space; an empty name restores "Desktop N"
set_space_noteAttach a short note to a Space
open_overviewOpen Spacepal's overview grid
list_profilesNames of your saved profiles
apply_profileApply a saved profile (names, colours, notes and automations)
apply_templateName the Spaces from a starter template: Developer, Designer, Freelancer, Student, Streamer
set_up_spaceSwitch to a Space and run its automations: open its apps, URLs and files
save_window_layoutSave which Space and position every window is in
restore_window_layoutPut windows back from the last saved layout
save_sessionsSave terminal sessions and Chrome windows on one Space or all of them
restore_sessionsReopen saved sessions on their Spaces
place_windowPut the front window in a half, a quarter, maximized, centred, or on the next display
set_presentation_modeHide Space names, notes and previews for a screen share, or show them again
add_desktopAdd a desktop on the current display
remove_desktopRemove a desktop; its windows move to another one

Every tool is marked with MCP hints, so clients can tell the read-only tools apart and ask before remove_desktop or apply_template, which change your setup.

move_window_to_space acts on the frontmost window. In Claude Desktop that is usually Claude's own window. It moves the window directly on macOS 14.0–14.4 and 26.4+, and by dragging it on other versions. restore_window_layout can only move windows between Spaces on 14.0–14.4 and 26.4+.

The MCP server is free. The tools follow the app's own limits: after Spacepal's 14-day trial, names and notes stay free, while the overview, sessions and other Pro features need a license.

Install

Claude Code

claude mcp add spacepal -- npx -y spacepal-mcp

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude:

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

Cursor

Add the same block to ~/.cursor/mcp.json, or to .cursor/mcp.json in a project:

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

From source

cd mcp && npm install
claude mcp add spacepal -- node "$PWD/index.js"

Troubleshooting

  • "Spacepal is not running": open Spacepal from Applications.
  • Names are out of date: Spacepal rewrites state.json when Spaces change. Open its menu once to refresh it.
  • Switching does nothing: check Spacepal > Settings > Setup. It needs Accessibility permission.

MIT © Halberd LLC