keyboard-maestro-mcp
You can control Keyboard Maestro from an MCP client: manage macros, actions, triggers, groups, variables, execution, and logs.
Search, list, inspect, create, clone, delete, enable/disable, run, and move macros.
Export or replace macro XML definitions.
List, add, move, delete, inspect, and edit macro actions by XML or search/replace.
Add, delete, inspect, and replace macro triggers.
Create, delete, toggle, and list macro groups.
Get, set, and delete Keyboard Maestro variables.
Inspect engine logs and recent macro errors.
Use simplified helpers to add notifications, pauses, variable set/calculation actions, display text, if-then-else logic, execute-macro steps, and shell scripts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@keyboard-maestro-mcp Run my morning routine macro"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: MCP Mac Apps Server
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." |
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 setupThe 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 |
| Find macros by name |
| List all macros |
| Get macro details |
| Export a macro's full definition |
| Build a new macro |
| Duplicate an existing macro |
| Remove a macro |
| Turn macros on/off |
| Execute a macro right now |
| Organize macro groups |
Action Editing
Tool | What it does |
| See all steps in a macro |
| Add a new step |
| Reorder steps |
| Remove a step |
| Export a step's definition |
| Replace a step |
| Find and replace text in a step |
Trigger Editing
Tool | What it does |
| Add a new trigger |
| Remove a trigger |
| Export a trigger |
| Replace a trigger |
Variables and Logs
Tool | What it does |
| Read, write, or delete KM variables |
| Find recent macro failures |
| Search the engine log |
Support
Having issues? Open an issue on GitHub
If you like this project, please consider giving the repo a ⭐ star!
npm run verify
npx @modelcontextprotocol/inspector node build/index.js{
"mcpServers": {
"keyboard-maestro": {
"command": "node",
"args": ["/path/to/keyboard-maestro-mcp/build/index.js"]
}
}
}A community project. Not affiliated with Stairways Software.
Available Tools
34 toolskm_add_actionC
Add an action to an existing macro using XML.
Inputs: actionXml (required), macroIdentifier (required).
km_add_calculationB
Add an action to set a variable to the result of a calculation (e.g., "Counter + 1").
Inputs: variable (required), expression (required), macroIdentifier (required).
km_add_display_textB
Add an action to display text in a window.
Inputs: text (required), title (required), macroIdentifier (required).
km_add_execute_macroC
Add an action to execute another macro.
Inputs: macroToExecute (required), macroIdentifier (required), parameter.
km_add_if_calculationB
Add an If-Then-Else action that checks a calculation condition (e.g., "Counter >= 5").
Inputs: calculation (required), macroIdentifier (required), elseActionsXml, thenActionsXml.
km_add_if_variable_containsB
Add an If-Then-Else action that checks if a variable contains a value.
Inputs: variable (required), containsValue (required), macroIdentifier (required), elseActionsXml, +1 more.
km_add_notificationA
Add a notification action to a macro. Much simpler than using km_add_action with raw XML.
Inputs: title (required), message (required), macroIdentifier (required), subtitle.
km_add_pauseC
Add a pause action to a macro.
Inputs: seconds (required), macroIdentifier (required).
km_add_set_variableC
Add an action to set a variable to a text value.
Inputs: value (required), variable (required), macroIdentifier (required).
km_add_shell_scriptB
Add an action to execute a shell script.
Inputs: script (required), macroIdentifier (required), saveToVariable.
km_add_triggerC
Add a trigger to a macro using XML.
Inputs: triggerXml (required), macroIdentifier (required).
km_clone_macroB
Duplicate an existing macro. Optionally provide a new name.
Inputs: identifier (required), newName.
km_create_macroA
Create a new macro with a name. Optionally include action XML to add an initial action.
Inputs: name (required), actionXml, groupName.
km_delete_actionA
Delete a specific action from a macro. Actions are 1-indexed. WARNING: This cannot be undone!
Inputs: actionIndex (required), macroIdentifier (required).
km_delete_macroA
Delete a macro by name or UID. WARNING: This cannot be undone!
Inputs: identifier (required).
km_delete_triggerA
Delete a trigger from a macro. Triggers are 1-indexed.
Inputs: triggerIndex (required), macroIdentifier (required).
km_enable_macroC
Enable or disable a macro.
Inputs: enabled (required), identifier (required).
km_get_action_xmlA
Get the XML definition of a specific action in a macro. Actions are 1-indexed.
Inputs: actionIndex (required), macroIdentifier (required).
km_get_errorsA
Get recent errors and failures from Keyboard Maestro Engine log. Returns errors grouped by macro with timestamps and error messages.
Inputs: hours.
km_get_logB
Get raw log entries from Keyboard Maestro Engine log with optional filters.
Inputs: lines, errorsOnly, macroFilter.
km_get_macroB
Get details about a specific macro by name or UID.
Inputs: identifier (required).
km_get_macro_xmlA
Get the full XML definition of a macro. Useful for understanding macro structure or creating similar macros.
Inputs: identifier (required).
km_get_trigger_xmlB
Get the XML definition of a specific trigger in a macro. Triggers are 1-indexed.
Inputs: triggerIndex (required), macroIdentifier (required).
km_list_actionsA
List all actions in a macro with their index, name, and enabled status.
Inputs: macroIdentifier (required).
km_list_macrosA
List all macros in Keyboard Maestro with their names and UIDs.
Inputs: no named parameters.
km_manage_groupB
Manage macro groups (create, delete, toggle, list).
Inputs: action (required), enabled, identifier.
km_manage_variableC
Manage Keyboard Maestro variables (get, set, delete).
Inputs: name (required), action (required), value.
km_move_actionA
Move an action to a new position index. Subsequent actions will shift down.
Inputs: newIndex (required), actionIndex (required), macroIdentifier (required).
km_move_macroB
Move a macro to a different macro group.
Inputs: groupIdentifier (required), macroIdentifier (required).
km_run_macroB
Execute a macro by name or UID.
Inputs: identifier (required), parameter.
km_search_macrosA
Search for macros by name (case-insensitive partial match). returns name and UID.
Inputs: query (required).
km_search_replace_actionB
Search and replace text within a specific action in a macro. Useful for fixing typos or updating values.
Inputs: searchText (required), actionIndex (required), replaceText (required), macroIdentifier (required).
km_set_action_xmlB
Set/replace the XML of a specific action in a macro. Use km_get_action_xml first to get the current XML.
Inputs: xml (required), actionIndex (required), macroIdentifier (required).
km_set_trigger_xmlA
Set/replace the XML of a specific trigger in a macro. Use km_get_trigger_xml first to understand the format.
Inputs: xml (required), triggerIndex (required), macroIdentifier (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 34 tools
Tools have mostly distinct purposes (e.g., adding specific action types, managing macros, triggers, groups). Some overlap exists between the generic km_add_action and the specialized add tools, but descriptions clarify when to use each.
All tools follow the 'km_verb_noun' pattern strictly, using snake_case. The verbs (add, create, delete, get, set, etc.) are clearly delineated, making the tool surface highly predictable.
34 tools is on the higher side but justified by the scope of automating Keyboard Maestro. Some redundancy (e.g., km_add_action vs. specific add tools) could be trimmed, but overall the count is borderline appropriate.
The tool set covers the full lifecycle of macros, actions, triggers, groups, and variables, plus logs and search. There are no obvious gaps for common macro automation tasks.
Maintenance
Related MCP Connectors
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Build and run agents and automations across hundreds of apps using natural language.
Streamline your Attio workflows using natural language to search, create, update, and organize com…
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage n8n automation workflows through natural language commands, including creating, executing, monitoring, and organizing workflows with full CRUD operations and execution management.122 npm2MIT
- AlicenseCqualityDmaintenanceEnables control of macOS applications through natural language, allowing users to launch apps, execute AppleScript commands, manage running applications, and open files with voice or text commands.15MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to control and interact with BetterTouchTool on macOS, allowing users to query configurations, execute triggers and actions, manage variables and widgets, control presets, and access clipboard contents through natural language.203MIT
- AlicenseNot gradedqualityDmaintenanceAn advanced macOS automation toolkit that enables AI clients to directly control a machine through deep integration with Keyboard Maestro. It provides a comprehensive suite of tools for executing macros, managing variables, and performing complex system automation with enterprise-grade security.13MIT