Moom MCP Server
A Model Context Protocol (MCP) server that enables programmatic control of Moom window layouts on macOS through natural language commands in Claude Desktop.
Overview
This MCP server allows Claude to interact with Moom, a powerful macOS window management tool, enabling you to:
- Switch between saved window layouts
- Create new window arrangements with pixel-perfect precision
- Control window positioning and sizing across multiple monitors
- Manage your workspace layouts through conversational commands
- NEW: DisplayPlacer integration for exact multi-monitor positioning
Features
- 🖼️ activate_layout - Instantly switch to any saved Moom layout
- 💾 save_current_layout - Save your current window arrangement as a reusable layout
- 🎯 trigger_moom_action - Execute Moom window actions (resize, move, center, etc.)
- 📋 show_moom_menu - Display the Moom popup menu
- 🖥️ DisplayPlacer Integration - Pixel-perfect multi-monitor window positioning
- 📐 Precision Layouts - Exact coordinate-based window management
Prerequisites
- macOS (10.12 or later)
- Moom installed and running
- Node.js 14 or higher
- Claude Desktop app
- Terminal app with accessibility permissions
- Optional: DisplayPlacer for enhanced multi-monitor support
Installation
-
Clone this repository:
git clone https://github.com/itrimble/moom-mcp.git cd moom-mcp -
Install dependencies:
npm install -
Grant accessibility permissions:
- Open System Preferences → Security & Privacy → Privacy → Accessibility
- Add and enable Terminal (or your terminal app)
- Add and enable Claude Desktop
-
Add to Claude Desktop configuration:
- Open Claude Desktop
- Navigate to Settings → Developer → Edit Config
- Add the following to your
claude_desktop_config.json:
{ "mcpServers": { "moom": { "command": "node", "args": ["/absolute/path/to/moom-mcp/src/index.js"] } } } -
Restart Claude Desktop
Usage
Once installed, you can use natural language commands in Claude Desktop:
Activating Layouts
- "Switch to my Teaching (Mac Mini) layout"
- "Activate the AI Research Mode workspace"
- "Use my coding layout"
- NEW: "Switch to DisplayPlacer Coding Pro" (pixel-perfect positioning)
Saving Layouts
- "Save the current window arrangement as 'Focus Mode'"
- "Create a new layout called 'Video Editing'"
Window Actions
- "Make this window bigger" (grow)
- "Center the active window"
- "Move window to the left"
- "Fill the screen with current window"
Menu Access
- "Show the Moom menu"
- "Open Moom's layout picker"
Multi-Monitor Precision (NEW)
- "Create a DisplayPlacer coding layout" (uses exact coordinates)
- "Position windows with pixel precision"
- "Optimize for my 4K display setup"
Available Commands
| Command | Description | Example |
|---|---|---|
activate_layout | Switch to a saved Moom layout | { "layoutName": "Teaching (Mac Mini)" } |
save_current_layout | Save current window arrangement | { "layoutName": "Development Setup" } |
trigger_moom_action | Execute window actions | { "action": "center" } |
show_moom_menu | Display Moom popup menu | {} |
Supported Window Actions
grow- Increase window sizeshrink- Decrease window sizemove-left- Move window leftmove-right- Move window rightmove-up- Move window upmove-down- Move window downcenter- Center window on screenfill-screen- Maximize window
DisplayPlacer Integration
The server now includes advanced multi-monitor support using DisplayPlacer:
Benefits
- Pixel-perfect positioning using exact display coordinates
- Multi-monitor awareness with proper origin calculation
- 4K display optimization with scaling consideration
- High refresh rate support (120Hz+)
- Negative coordinate handling for left-positioned displays
Enhanced Layouts
- DisplayPlacer Coding Pro: Precision layout for development
- Ultimate Multi-Monitor Pro: Full display utilization across all monitors
Installation (Optional)
brew install jakehilborn/jakehilborn/displayplacer
Project Structure
moom-mcp/
├── src/
│ ├── index.js # Main MCP server implementation
│ └── displayplacer-layouts.js # DisplayPlacer integration module
├── examples.md # Usage examples and workflows
├── test.js # Basic functionality tests
├── test-ui.js # UI automation tests
├── validate.js # Configuration validator
├── demo.js # Feature demonstration
├── package.json # Node.js configuration
├── LICENSE # MIT License
└── README.md # This file
Development
Testing
Run the test suite:
npm test # Basic tests
npm run test-ui # UI automation tests
npm run validate # Validate configuration
Debugging
-
Check if Moom is running:
pgrep -x Moom -
Verify accessibility permissions are granted
-
Run the validation script:
npm run validate
Troubleshooting
"Error accessing Moom menu"
- Ensure Moom is running
- Verify accessibility permissions for Terminal and Claude Desktop
- Check that Moom's menu bar icon is visible
Layouts not activating
- Layout names are case-sensitive
- Verify the exact layout name in Moom preferences
- Special characters in layout names may need escaping
MCP not loading in Claude
- Restart Claude Desktop after configuration changes
- Check the config file path is absolute
- Verify Node.js is in your PATH
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Author
Ian Trimble - GitHub
Acknowledgments
- Many Tricks for creating Moom
- Anthropic for the Model Context Protocol
- The MCP community for inspiration and examples