Skip to main content
Glama
keyboard-maestro-mcp

keyboard-maestro-mcp

by saihgupr

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."

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

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 tools
km_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

    A3.5/5.0

    Scored across 34 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers