Control your Spaces from Claude and Cursor
The Spacepal MCP server lets AI agents that speak the Model Context Protocol work with your macOS Spaces: "switch to my Mail Space", "what's open on Desktop 3?", "name this desktop Research". It runs on your Mac over stdio, needs Spacepal running, and makes no network calls. It is free and open source (MIT).
Install
You need macOS 14 or later, Spacepal running and Node.js 18 or later.
Claude Code
claude mcp add spacepal -- npx -y spacepal-mcpClaude Desktop
Add this to ~/Library/Application Support/Claude/claude_desktop_config.json and 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.
Tools
| Tool | What it does |
|---|---|
list_spaces | Every Space with its number, name, display, apps, and which one is active |
current_space | The Space you are on |
switch_space | Switch by number or name, or step with next, previous, back |
move_window_to_space | Send the frontmost window to a Space by number or name |
rename_space | Name a Space; an empty name restores "Desktop N" |
open_overview | Open Spacepal's overview grid |
set_space_note | Attach a short note to a Space |
apply_profile | Apply a saved Spacepal profile |
How it works and its limits
- The server reads the list of Spaces from the
state.jsonfile Spacepal keeps up to date and runs every action through aspacepal://link, the same links described in the URL scheme docs. - If Spacepal is not running, every tool answers "Spacepal is not running" instead of failing silently.
move_window_to_spaceacts on the frontmost window. In Claude Desktop that is usually Claude's own window; from Claude Code it is the window you were last working in.- Space names, apps and notes stay on your Mac. They are passed to the AI client you connected, as with any MCP tool.
Related
Written by Dan Bayer, developer of Spacepal. Last updated 2026-10-30.