Keyboard Maestro MCP

An MCP server for Keyboard Maestro. Manage your macros with natural language commands.

What Can You Do?

Instead of digging through menus and clicking buttons, just ask:

| Just say... | |-------------| | "Run my morning routine macro" | | "Create a macro that types my email signature when I press Cmd+Shift+S" | | "What macros have been failing lately? Fix them." | | "Duplicate my 'Open Project' macro and modify it for the new client" | | "Disable all my work macros, I'm on vacation" |

Your AI assistant becomes a power user of your Mac. It can read, create, modify, run, and debug your Keyboard Maestro macros through conversation.

Real-World Examples

| Use Case | Example | |----------|---------| | Debugging | "My clipboard manager macro stopped working yesterday. Check the logs and tell me what went wrong." | | Bulk Editing | "I have 20 macros that open Chrome. Change them all to open Arc instead." | | Quick Automation | "Make a macro that mounts my NAS drives when I connect to my home WiFi." | | Organization | "Create a new macro group called 'Client Work' and move all macros with 'ACME' in the name into it." |

[!IMPORTANT] This MCP gives your AI full access to Keyboard Maestro. It can run, modify, and delete macros. Always review suggested changes before approving them.

Requirements

• macOS (Keyboard Maestro is macOS-only)
• Keyboard Maestro installed and running
• Node.js v18+

Quick Start

git clone https://github.com/saihgupr/keyboard-maestro-mcp.git
cd keyboard-maestro-mcp
npm install
npm run setup

The setup wizard will configure your AI client automatically. It supports:

• Claude Desktop
• Cursor
• VS Code (Copilot)
• Windsurf
• Antigravity
• Any MCP-compatible client

Available Tools

Macro Management

| Tool | What it does | |------|--------------| | km_search_macros | Find macros by name | | km_list_macros | List all macros | | km_get_macro | Get macro details | | km_get_macro_xml | Export a macro's full definition | | km_create_macro | Build a new macro | | km_clone_macro | Duplicate an existing macro | | km_delete_macro | Remove a macro | | km_enable_macro | Turn macros on/off | | km_run_macro | Execute a macro right now | | km_manage_group | Organize macro groups |

Action Editing

| Tool | What it does | |------|--------------| | km_list_actions | See all steps in a macro | | km_add_action | Add a new step | | km_move_action | Reorder steps | | km_delete_action | Remove a step | | km_get_action_xml | Export a step's definition | | km_set_action_xml | Replace a step | | km_search_replace_action | Find and replace text in a step |

Trigger Editing

| Tool | What it does | |------|--------------| | km_add_trigger | Add a new trigger | | km_delete_trigger | Remove a trigger | | km_get_trigger_xml | Export a trigger | | km_set_trigger_xml | Replace a trigger |

Variables and Logs

| Tool | What it does | |------|--------------| | km_manage_variable | Read, write, or delete KM variables | | km_get_errors | Find recent macro failures | | km_get_log | Search the engine log |

Testing Your Setup

Quick check:

npm run verify

Interactive testing:

npx @modelcontextprotocol/inspector node build/index.js

Manual Configuration

If you prefer to configure manually, add this to your AI client's MCP config:

{
  "mcpServers": {
    "keyboard-maestro": {
      "command": "node",
      "args": ["/path/to/keyboard-maestro-mcp/build/index.js"]
    }
  }
}

Support

Having issues? Open an issue on GitHub

If you like this project, please consider giving the repo a ⭐ star!