Keyboard Maestro

You can control macOS automation directly from a client through the Keyboard Maestro MCP Server. It exposes a robust MCP interface that lets you run macros, manage KM variables, monitor server health, and perform advanced automation with secure, high-performance execution on the host machine.

How to use

Connect to the server from your MCP client to start automating Keyboard Maestro on your Mac. You can execute macros by name or UUID, list available macros, manage KM variables across scopes, and perform advanced searches and analyses on macros. Real-time synchronization tools keep your local macro library in sync with the server. Begin by starting the MCP server via your configuration and then issue commands from your client to perform actions such as running a macro, querying macros, or retrieving server status.

How to install

Prerequisites: install and run on macOS with Keyboard Maestro installed and accessible. You also need Python 3.10 or later and a compatible MCP runtime such as uvx.

1. Prepare your environment. Create and activate a Python virtual environment.

2. Install the MCP runtime and dependencies using the recommended method.

3. Configure Keyboard Maestro to allow web server access on port 4490 and grant accessibility permissions if prompted.

4. Start the MCP server using the development runtime command provided in your configuration.

Configuration and environment

The server is configured to listen for MCP clients using a stdio-based runtime. You can start the server with the following command, which runs the server via uv and Python, pointing to the main entry point for dynamic registration.

{
  "mcpServers": {
    "keyboard_maestro": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "src.main_dynamic"],
      "env": {
        "KM_WEB_SERVER_PORT": "4490",
        "KM_CONNECTION_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    },
    "keyboard_maestro_dev": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/Users/YOUR_USERNAME/path/to/keyboard-maestro-mcp", "run", "python", "-m", "src.main_dynamic"],
      "env": {
        "KM_WEB_SERVER_PORT": "4490",
        "KM_CONNECTION_TIMEOUT": "30",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Security and environment variables

Security is enforced through multi-level validation, input sanitization, and a permission system to prevent unauthorized access or harmful automation. You can tune security levels and observe audit logs to track operations.

Environment variables you may configure include KM_WEB_SERVER_PORT, KM_CONNECTION_TIMEOUT, LOG_LEVEL, and SECURITY_LEVEL. Use KM_WEB_SERVER_PORT to set the web server port (default 4490), KM_CONNECTION_TIMEOUT to define connection timeouts in seconds, LOG_LEVEL to control logging output, and SECURITY_LEVEL to adjust validation strictness.

Usage patterns and tools overview

Common actions you perform through the MCP server include executing macros, listing macros, managing KM variables, advanced macro search, macro metadata analysis, and macro group insights. You also have real-time synchronization controls to start, stop, and check status of library synchronization.

Troubleshooting and notes

If the server fails to start, verify that Keyboard Maestro’s Web Server is enabled and that accessibility permissions were granted if prompted. Check that the specified port (4490 by default) is not blocked and that the Python environment is active. Review logs for security-related messages if you encounter access issues.

Available tools

km_execute_macro

Execute Keyboard Maestro macros with comprehensive error handling, from the MCP client to control your macOS system.

km_list_macros

List and filter Keyboard Maestro macros with search capabilities to discover automation options.

km_variable_manager

Manage Keyboard Maestro variables across all scopes (global, local, instance, password) including get/set/delete/list operations.

km_search_macros_advanced

Advanced macro search with filtering by scope, categories, complexity, and metadata.

km_analyze_macro_metadata

Deep analysis of macro metadata and patterns to extract insights.

km_list_macro_groups

List macro groups with statistics such as macro counts and enabled counts.

km_start_realtime_sync

Start real-time synchronization of the macro library.

km_stop_realtime_sync

Stop real-time synchronization of the macro library.

km_sync_status

Get synchronization status with metrics.

km_force_sync

Force immediate synchronization of the macro library.