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!

Keyboard Maestro MCP