Moom MCP

🚀 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.

🚀 Quick Start

This MCP server allows Claude to interact with Moom, a powerful macOS window management tool. You can use natural language commands in Claude Desktop to achieve various window management operations after installation.

✨ 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

📦 Installation

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

Steps

1. Clone this repository:

   git clone https://github.com/itrimble/moom-mcp.git
   cd moom-mcp
   

2. Install dependencies:

   npm install
   

3. Grant accessibility permissions:

   • Open System Preferences → Security & Privacy → Privacy → Accessibility
   • Add and enable Terminal (or your terminal app)
   • Add and enable Claude Desktop

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

5. Restart Claude Desktop

💻 Usage Examples

Basic 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"

📚 Documentation

Available Commands

Supported Window Actions

• grow - Increase window size
• shrink - Decrease window size
• move-left - Move window left
• move-right - Move window right
• move-up - Move window up
• move-down - Move window down
• center - Center window on screen
• fill-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

1. Check if Moom is running:

   pgrep -x Moom
   

2. Verify accessibility permissions are granted

3. 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

📚 Related Projects

• Model Context Protocol
• Moom by Many Tricks