Keyboard Maestro MCP Server

An MCP server that lets a client drive Keyboard Maestro on macOS — run macros, manage variables, configure triggers and hotkeys, edit macros, and exercise the Keyboard Maestro Engine.

This server only controls Keyboard Maestro. It does not embed an LLM, vision model, IoT controller, voice recognizer, analytics engine, identity layer, or raw mouse/keyboard simulator — those belong elsewhere (the computer-use MCP covers raw input and screen interaction).

Tool surface (27 tools)

Auto-discovered from src/server/tools/ at startup. Each tool routes through src/integration/km_client.py to the Keyboard Maestro Engine via AppleScript or the KM web server.

Some tools currently have partial XML emitters (km_add_condition, km_control_flow, km_create_macro for non-custom templates). km_action_builder covers seven action types end-to-end (pause, type_text, paste, set_variable, run_applescript, execute_macro, plug_in); to add another built-in type, add a branch in action_builder_tools._build_action_xml and a registry entry in action_tools._BUILTIN_ACTION_TYPES in the same change. See docs/km_mcp_audit_report.md for the known-stub matrix.

Related MCP server: MCP AppleScript

Install

git clone https://github.com/anthropics/keyboard-maestro-mcp.git
cd keyboard-maestro-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,test]"

Prerequisites:

• macOS 10.15+

• Python 3.10+

• Keyboard Maestro 10.0+ with Web Server enabled (Preferences → Web Server)

• Accessibility permissions granted to the Python interpreter

Run

km-mcp-server
# or
python -m src.main_dynamic

Claude Desktop configuration

In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "keyboard-maestro": {
      "command": "/absolute/path/to/keyboard-maestro-mcp/.venv/bin/python",
      "args": ["-m", "src.main_dynamic"],
      "cwd": "/absolute/path/to/keyboard-maestro-mcp",
      "env": {
        "KM_WEB_SERVER_PORT": "4490",
        "KM_CONNECTION_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Architecture

src/
├── main_dynamic.py          # FastMCP server entry point
├── server/
│   ├── tool_registry.py     # Auto-discovers km_* functions from src/server/tools/
│   ├── dynamic_registration.py
│   ├── tool_config.py       # Security policy overrides per tool
│   └── tools/               # 19 tool modules — each km_* function becomes an MCP tool
├── integration/
│   ├── km_client.py         # Single bridge to Keyboard Maestro (AppleScript + HTTP)
│   ├── km_conditions.py     # KM condition spec generation
│   ├── km_triggers.py       # KM trigger spec generation
│   ├── km_control_flow.py   # KM if/while/for action insertion
│   └── km_macro_editor.py   # KM macro modification operations
├── core/                    # Engine abstractions, types, errors, contracts
└── security/                # Input sanitization + validation

All MCP tools live in src/server/tools/ and depend inward on src/core/, src/integration/, and src/security/. There is exactly one client to Keyboard Maestro (src/integration/km_client.py); tools never speak AppleScript directly.

License

MIT