keyboard-maestro

Keyboard Maestro MCP exposes a set of tools to manage and automate Keyboard Maestro macros through natural language commands. With this server, you can search for macros, inspect their details, create new macros, clone or delete existing ones, run macros on demand, and reorganize macro groups. You also have tools to view and edit the steps that comprise a macro (actions), modify triggers, and manage KM variables and logs. The included testing commands help verify your setup and interactively inspect the MCP runtime.

To use the tools, run the MCP server as configured (for example via node /path/to/keyboard-maestro-mcp/build/index.js). The available tools are organized into categories such as Macro Management, Action Editing, Trigger Editing, and Variables & Logs. You can perform high-level operations like creating a new macro, duplicating an existing one, or running a macro right away. You can also inspect a macro’s full XML definition or export individual actions or triggers for editing elsewhere. Always review suggested changes before applying them, as the MCP server has full access to Keyboard Maestro and can modify or delete macros.

Prerequisites

• macOS with Keyboard Maestro installed and running
• Node.js v18+ installed
• Internet access to install dependencies

Installation steps

1. Clone the repository

git clone https://github.com/saihgupr/keyboard-maestro-mcp.git
cd keyboard-maestro-mcp

2. Install dependencies

npm install

3. Run the setup (if you want the AI client to auto-configure)

npm run setup

4. Start the MCP server (example)

npm run start

5. If you prefer manual configuration, ensure your MCP config points to the built entry (see Manual Configuration in README)

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

Testing

• Quick check:

npm run verify

• Interactive testing (from README):

npx @modelcontextprotocol/inspector node build/index.js

Tips and considerations:

• This MCP provides full access to Keyboard Maestro; review AI-generated changes before applying.
• Ensure Keyboard Maestro is running and accessible to the MCP process on macOS.
• If you move the project, update the path in the mcp_config entry to point to build/index.js.
• You can customize environment variables in the mcp_config under env if your setup requires specific KM paths or logging settings.
• For troubleshooting, use km_get_errors and km_get_log to inspect recent macro failures and engine logs.