macos-automator-mcp

# macOS Automator MCP 🤖 - Your Friendly Neighborhood RoboScripter™  ## 🎯 Mission Control: Teaching Robots to Click Buttons Since 2024 Welcome to the automated future where your Mac finally does what you tell it to! This Model Context Protocol (MCP) server transforms your AI assistant into a silicon-based intern who actually knows AppleScript and JavaScript for Automation (JXA). No more copy-pasting scripts like a caveman - let the robots handle the robot work! Our knowledge base contains over 200 pre-programmed automation sequences, loaded faster than you can say "Hey Siri, why don't you work like this?" ## 🚀 Why Let Robots Run Your Mac? - **Remote Control Reality**: Execute AppleScript/JXA scripts via MCP - it's like having a tiny robot inside your Mac! - **Knowledge Base of Power**: 200+ pre-built automation recipes. From "toggle dark mode" to "extract all URLs from Safari" - we've got your robot needs covered. - **App Whisperer**: Control any macOS application programmatically. Make Finder dance, Safari sing, and Terminal... well, terminate things. - **AI Workflow Integration**: Connect your Mac to the AI revolution. Your LLM can now actually DO things instead of just talking about them! ## 🔧 Robot Requirements (Prerequisites) - **Node.js** (version >=18.0.0) - Because even robots need a runtime - **macOS** - Sorry Windows users, this is an Apple-only party 🍎 - **⚠️ CRITICAL: Permission to Automate (Your Mac's Trust Issues):** - The application running THIS MCP server (e.g., Terminal, your Node.js application) requires explicit user permissions on the macOS machine where the server is running. - **Automation Permissions:** To control other applications (Finder, Safari, Mail, etc.). - Go to: System Settings > Privacy & Security > Automation. - Find the application running the server (e.g., Terminal) in the list. - Ensure it has checkboxes ticked for all applications it needs to control. - See example: `docs/automation-permissions-example.png` (placeholder image). - **Accessibility Permissions:** For UI scripting via "System Events" (e.g., simulating clicks, keystrokes). - Go to: System Settings > Privacy & Security > Accessibility. - Add the application running the server (e.g., Terminal) to the list and ensure its checkbox is ticked. - First-time attempts to control a new application or use accessibility features may still trigger a macOS confirmation prompt, even if pre-authorized. The server itself cannot grant these permissions. ## 🏃‍♂️ Quick Start: Release the Robots! The easiest way to deploy your automation army is via `npx`. No installation needed - just pure robot magic! Add this to your MCP client's `mcp.json` and watch the automation begin: ```json { "mcpServers": { "macos_automator": { "command": "npx", "args": [ "-y", "@steipete/macos-automator-mcp@latest" ] } } } ``` ### 🛠️ Robot Workshop Mode (Local Development) Want to tinker with the robot's brain? Clone the repo and become a robot surgeon! 1. **Clone the repository:** ```bash git clone https://github.com/steipete/macos-automator-mcp.git cd macos-automator-mcp npm install # Ensure dependencies are installed ``` 2. **Configure your MCP client:** Update your MCP client's configuration to point to the absolute path of the `start.sh` script within your cloned repository. Example `mcp.json` configuration snippet: ```json { "mcpServers": { "macos_automator_local": { "command": "/absolute/path/to/your/cloned/macos-automator-mcp/start.sh", "env": { "LOG_LEVEL": "DEBUG" } } } } ``` **Important:** Replace `/absolute/path/to/your/cloned/macos-automator-mcp/start.sh` with the correct absolute path on your system. The `start.sh` script will automatically use `tsx` to run the TypeScript source directly if a compiled version is not found, or run the compiled version from `dist/` if available. It respects the `LOG_LEVEL` environment variable. **Note for Developers:** The `start.sh` script, particularly if modified to remove any pre-existing compiled `dist/server.js` before execution (e.g., by adding `rm -f dist/server.js`), is designed to ensure you are always running the latest TypeScript code from the `src/` directory via `tsx`. This is ideal for development to prevent issues with stale builds. For production deployment (e.g., when published to npm), a build process would typically create a definitive `dist/server.js` which would then be the entry point for the published package. ## 🤖 Robot Toolbox ### 1. `execute_script` - The Script Launcher 9000 Your robot's primary weapon for macOS domination. Feed it AppleScript or JXA, and watch the magic happen! Scripts can be provided as inline content (`script_content`), an absolute file path (`script_