nqkdev/mcp-macos-automation

macOS Automation MCP Server

An MCP (Model Context Protocol) server that enables AI assistants to automate macOS UI interactions using AppleScript.

Features

• Messenger automation - Send messages via Facebook Messenger app
• Slack automation - Send messages via Slack app with whitelist protection
• Application control - Open applications
• AppleScript execution - Execute arbitrary AppleScript for custom automation
• Robust cold start handling - Automatically detects and waits for apps to fully load
• Clipboard-based input - Avoids keyboard layout issues (VNI, Telex, etc.)
• Unicode support - Handles Vietnamese, emojis, and special characters
• Security whitelist - Prevent accidental messages to wrong recipients
• Extensible - Easy to add new automation tools

Installation

npm install
npm run build

Usage

As an npx command

After building, you can run the server with:

npx mcp-macos-automation

Configure in Claude Desktop

Add to your ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "macos-automation": {
      "command": "npx",
      "args": ["-y", "./mcp-macos-automation"],
      "env": {
        "WHITELISTED_SLACK_HANDLES": "user@company.com,general",
        "WHITELISTED_MESSENGER_HANDLES": "User One,User Two"
      }
    }
  }
}

Or if you publish to npm:

{
  "mcpServers": {
    "macos-automation": {
      "command": "npx",
      "args": ["-y", "mcp-macos-automation"],
      "env": {
        "WHITELISTED_SLACK_HANDLES": "user@company.com,general",
        "WHITELISTED_MESSENGER_HANDLES": "User One"
      }
    }
  }
}

Configuration

Environment Variables

WHITELISTED_SLACK_HANDLES (optional)

• Comma-separated list of Slack channels/DMs to whitelist
• When set, only allows sending messages to whitelisted channels
• Names must match exactly as they appear in Slack
• Example: "user1,user2,general,random"

WHITELISTED_MESSENGER_HANDLES (optional)

• Comma-separated list of Messenger conversations to whitelist
• When set, only allows sending messages to whitelisted recipients
• Names must match exactly as they appear in Messenger
• Example: "User One,User Two,Family Group"

Available Tools

send_messenger_message

Send a message via Facebook Messenger app.

Parameters:

• recipient (string, required) - Recipient name as shown in Messenger
• message (string, required) - Message text to send

Requirements:

• Messenger app must be installed
• macOS Accessibility permissions required

Security:

• If WHITELISTED_MESSENGER_HANDLES is set, only allows sending to whitelisted recipients
• Prevents accidentally sending messages to wrong people

send_slack_message

Send a message via Slack app.

Parameters:

• channel (string, required) - Channel or person name as shown in Slack
• message (string, required) - Message text to send

Requirements:

• Slack app must be installed
• macOS Accessibility permissions required

Security:

• If WHITELISTED_SLACK_HANDLES is set, only allows sending to whitelisted channels
• Prevents accidentally sending messages to wrong people

open_application

Open a macOS application.

Parameters:

• application (string, required) - Application name (e.g., "Safari", "Notes")

execute_applescript

Execute arbitrary AppleScript code for macOS automation.

Parameters:

• script (string, required) - The AppleScript code to execute

Requirements:

• macOS Accessibility permissions may be required depending on the script
• Scripts run with a 30-second timeout

Example scripts:

• Get current volume: output volume of (get volume settings)
• Click menu item: tell application "System Events" to click menu item "New Window" of menu "File" of menu bar 1 of process "Safari"

macOS Permissions

This server requires the following macOS permissions:

1. Accessibility Access - Required for UI automation

   • Go to System Preferences → Security & Privacy → Privacy → Accessibility
   • Add Terminal (or your IDE) to the allowed list

2. Automation - May be prompted when first running scripts

   • Allow automation for the applications you want to control

Development

Watch mode for development:

npm run watch

Security Notes

• This server executes AppleScript with your user permissions
• Whitelist configuration prevents accidentally sending messages to wrong recipients
• Only use with trusted AI assistants
• Review automation scripts before executing them

Extending

To add new automation tools:

1. Add tool definition to TOOLS array
2. Create handler function
3. Add case to the tool handler switch statement

Troubleshooting

"Operation not permitted" errors:

• Grant Accessibility permissions to your Terminal/IDE

Messenger/Slack automation not working:

• Ensure apps are installed and logged in
• Check keyboard shortcuts match (Cmd+K for Slack, Cmd+F for Messenger)
• The server waits up to 5 seconds for apps to become ready
• Messages use clipboard paste to avoid keyboard layout issues

Timeouts:

• The server includes adaptive delays for cold starts (apps not running)
• AppleScript execution timeout is 30 seconds

License

MIT