controlmac-mcp

MCP Server for controlling macOS via AppleScript and system commands. Enables LLMs like Claude to interact with applications, system settings, notifications, clipboard, Finder, and more.

Features

• Core: Execute AppleScript/JXA code
• System: Volume, brightness, dark mode, system info, sleep, trash
• Apps: Open, quit, list, hide, show, get windows
• Notifications: Notifications, dialogs, alerts, text-to-speech
• Clipboard: Get, set, clear
• Finder: Open paths, reveal, selected files, current path, new window, open URLs

Installation

Using npx (Recommended)

No installation required! Use directly with npx:

npx controlmac-mcp

Global Installation

npm install -g controlmac-mcp

From Source

git clone https://github.com/ramgeart/controlmac-mcp.git
cd controlmac-mcp
npm install
npm run build

Configuration

Claude Desktop (with npx)

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

{
  "mcpServers": {
    "controlmac": {
      "command": "npx",
      "args": ["-y", "controlmac-mcp"]
    }
  }
}

Claude Desktop (global install)

{
  "mcpServers": {
    "controlmac": {
      "command": "controlmac-mcp"
    }
  }
}

Claude Desktop (from source)

{
  "mcpServers": {
    "controlmac": {
      "command": "node",
      "args": ["/path/to/controlmac-mcp/dist/index.js"]
    }
  }
}

Available Tools (27)

| Tool | Description | |------|-------------| | macos_osascript | Execute AppleScript/JXA | | macos_set_volume | Set volume (0-100) | | macos_get_volume | Get volume settings | | macos_set_mute | Mute/unmute | | macos_set_brightness | Set brightness | | macos_get_system_info | Get system info | | macos_sleep_display | Sleep display | | macos_empty_trash | Empty Trash | | macos_set_dark_mode | Toggle dark mode | | macos_get_dark_mode | Get dark mode status | | macos_open_app | Open application | | macos_quit_app | Quit application | | macos_list_apps | List running apps | | macos_get_frontmost_app | Get focused app | | macos_hide_app | Hide app | | macos_show_all_apps | Show all apps | | macos_get_app_windows | Get app windows | | macos_notification | Show notification | | macos_dialog | Show dialog | | macos_alert | Show alert | | macos_speak | Text-to-speech | | macos_get_clipboard | Get clipboard | | macos_set_clipboard | Set clipboard | | macos_clear_clipboard | Clear clipboard | | macos_open_path | Open file/folder | | macos_reveal_in_finder | Reveal in Finder | | macos_get_selected_files | Get selected files | | macos_get_finder_path | Get Finder path | | macos_new_finder_window | New Finder window | | macos_open_url | Open URL |

Usage Examples

"Set volume to 50%" → macos_set_volume
"Open Safari" → macos_open_app
"Show a notification saying 'Done!'" → macos_notification
"Enable dark mode" → macos_set_dark_mode
"What apps are running?" → macos_list_apps

Releases

Releases are automated via GitHub Actions. To create a new release:

# Update version in package.json, then:
git add -A
git commit -m "chore: bump version to x.y.z"
git tag v1.0.0
git push origin main --tags

The workflow will:

1. Build and test the project
2. Create a GitHub Release with auto-generated notes
3. Publish to npm

Setup for Publishing

Add NPM_TOKEN secret to your repository:

1. Go to npmjs.com → Access Tokens → Generate New Token (Automation)
2. In GitHub repo → Settings → Secrets → Actions → New repository secret
3. Name: NPM_TOKEN, Value: your npm token

License

MIT