Keyboard Maestro MCP Server

An advanced macOS automation toolkit that deeply integrates Keyboard Maestro with AI through the Model Context Protocol (MCP). This server provides a robust set of production-ready tools specifically designed for comprehensive macOS computer automation, enabling the MCP client to directly control the machine the server is running on. It features enterprise-grade security, functional programming patterns, and property-based testing.

🚀 Features

Core Capabilities

• Macro Execution: Execute Keyboard Maestro macros with comprehensive error handling
• Variable Management: Manage KM variables across all scopes (global, local, instance, password)
• Trigger System: Event-driven macro triggers with functional state management
• Security Framework: Multi-level input validation and injection prevention
• Performance Optimization: Sub-second response times with intelligent caching

Advanced Architecture

• Functional Programming: Immutable data structures and pure functions
• Design by Contract: Pre/post conditions with comprehensive validation
• Type Safety: Branded types with complete type system
• Property-Based Testing: Focused hypothesis-driven behavior validation for core automation
• Security Boundaries: Defense-in-depth with threat modeling

MCP Integration

• FastMCP Framework: Modern Python MCP server implementation
• Core Production Tools: A comprehensive suite for client-driven macro automation and direct computer control
• Modular Architecture: Organized tools by functionality (core, advanced, sync, groups)
• Resource System: Server status and help documentation
• Prompt Templates: Intelligent macro creation assistance

📦 Installation

Prerequisites

• macOS: 10.15+ (Catalina or later)
• Python: 3.10+
• Keyboard Maestro: 10.0+ (for full functionality)
• Claude Desktop: Latest version

Setup Instructions

1. Clone the repository:

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

2. Install dependencies:

   # Create virtual environment
   python -m venv .venv
   source .venv/bin/activate
   
   # Install with uv (recommended)
   pip install uv
   uv sync
   
   # Or install with pip
   pip install -e ".[dev,test,security]"
   

3. Configure Keyboard Maestro:

   • Enable "Web Server" in Keyboard Maestro preferences
   • Set port to 4490 (default)
   • Grant accessibility permissions if prompted

4. Test the installation:

   # Run the server
   uv run python -m src.main_dynamic
   
   # Or with script entry point
   km-mcp-server --help
   

🔧 Claude Desktop Configuration

This configuration enables Claude Desktop to act as an MCP client, connecting to and controlling your local Keyboard Maestro MCP Server.

Add the following configuration to your Claude Desktop claude_desktop_config.json file:

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Content (Recommended)

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

Alternative Configuration (using uv for development)

{
  "mcpServers": {
    "keyboard-maestro": {
      "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"
      }
    }
  }
}

Important: Replace /Users/YOUR_USERNAME/path/to/keyboard-maestro-mcp with the actual path to your installation.

Environment Variables

Variable	Default	Description
KM_WEB_SERVER_PORT	4490	Keyboard Maestro web server port
KM_CONNECTION_TIMEOUT	30	Connection timeout in seconds
KM_CONNECTION_METHOD	applescript	Connection method (applescript, url, web)
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
SECURITY_LEVEL	STANDARD	Security validation level (MINIMAL, STANDARD, STRICT, PARANOID)

🛠️ Available Tools

The server provides a comprehensive suite of MCP tools for computer automation through Keyboard Maestro. Below are the primary tools for macro execution and control:

Core MCP Tools

1. km_execute_macro

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

Parameters:

• identifier (string): Macro name or UUID
• trigger_value (optional string): Parameter to pass to macro
• method (string): Execution method (applescript, url, web, remote)
• timeout (integer): Maximum execution time (1-300 seconds)

Example:

# Execute a macro by name
result = await km_execute_macro(
    identifier="Type Current Date",
    method="applescript",
    timeout=30
)

2. km_list_macros

List and filter Keyboard Maestro macros with search capabilities, enabling the MCP client to discover available automation options.

Parameters:

• group_filter (optional string): Filter by macro group
• enabled_only (boolean): Only return enabled macros
• sort_by (string): Sort field (name, last_used, created_date, group)
• limit (integer): Maximum results (1-100)

Example:

# List all macros in "Utilities" group
macros = await km_list_macros(
    group_filter="Utilities",
    enabled_only=True,
    sort_by="name",
    limit=20
)

3. km_variable_manager

Comprehensive variable management across all KM scopes, allowing the MCP client to manage Keyboard Maestro variables for dynamic automation.

Parameters:

• operation (string): Operation type (get, set, delete, list)
• name (optional string): Variable name
• value (optional string): Variable value (for set operation)
• scope (string): Variable scope (global, local, instance, password)
• instance_id (optional string): Instance ID for local/instance variables

Example:

# Set a global variable
result = await km_variable_manager(
    operation="set",
    name="CurrentProject",
    value="Keyboard Maestro MCP",
    scope="global"
)

# Get a variable value
value = await km_variable_manager(
    operation="get",
    name="CurrentProject",
    scope="global"
)

4. km_search_macros_advanced ✨ NEW

Advanced macro search with comprehensive filtering and metadata analysis.

Parameters:

• query (string): Search text for macro names, groups, or content
• scope (string): Search scope (name_only, name_and_group, full_content, metadata_only)
• action_categories (optional string): Filter by action types
• complexity_levels (optional string): Filter by complexity levels
• min_usage_count (integer): Minimum execution count filter
• sort_by (string): Advanced sorting criteria

5. km_analyze_macro_metadata ✨ NEW

Deep analysis of individual macro metadata and patterns.

Parameters:

• macro_id (string): Macro ID or name to analyze
• include_relationships (boolean): Include similarity and relationship analysis

6. km_list_macro_groups ✨ NEW

List all macro groups with comprehensive statistics.

Parameters:

• include_macro_count (boolean): Include count of macros in each group
• include_enabled_count (boolean): Include count of enabled macros
• sort_by (string): Sort groups by name, macro_count, or enabled_count

7-10. Real-time Synchronization Tools ✨ NEW

• km_start_realtime_sync: Start real-time macro library synchronization
• km_stop_realtime_sync: Stop real-time synchronization
• km_sync_status: Get synchronization status with metrics
• km_force_sync: Force immediate synchronization

Resources

• km://server/status: Server status and configuration
• km://help/tools: Comprehensive tool documentation

Prompts

• create_macro_prompt: Generate structured prompts for macro creation

🏗️ Architecture Overview

Project Structure

keyboard-maestro-mcp/
├── src/
│   ├── main_dynamic.py      # Main server entry point with dynamic registration
│   ├── core/                # Core engine and types
│   │   ├── engine.py        # Macro execution engine
│   │   ├── types.py         # Branded types and protocols
│   │   ├── contracts.py     # Design by Contract system
│   │   └── errors.py        # Error hierarchy
│   ├── integration/         # Keyboard Maestro integration
│   │   ├── events.py        # Functional event system
│   │   ├── km_client.py     # KM client with Either monad
│   │   ├── triggers.py      # Trigger management
│   │   ├── security.py      # Security validation
│   │   ├── macro_metadata.py # Enhanced metadata extraction
│   │   ├── smart_filtering.py # Advanced search capabilities
│   │   ├── sync_manager.py  # Real-time synchronization
│   │   └── file_monitor.py  # File system monitoring
│   ├── server/              # **MCP Server components enabling client control**
│   │   ├── initialization.py # Component initialization
│   │   ├── resources.py     # MCP resources and prompts
│   │   ├── utils.py         # Utility functions
│   │   └── tools/           # Comprehensive tool suite for computer automation
│   │       ├── core_tools.py         # Basic macro operations
│   │       ├── app_control_tools.py  # Application control
│   │       ├── window_tools.py       # Window management
│   │       ├── clipboard_tools.py    # Clipboard operations
│   │       ├── file_operation_tools.py # File system control
│   │       ├── hotkey_tools.py       # Hotkey management
│   │       ├── visual_automation_tools.py # Screen automation
│   │       └── [30+ specialized automation tools]
│   ├── commands/            # Macro command library for computer control
│   │   ├── text.py          # Text manipulation commands
│   │   ├── system.py        # System commands
│   │   ├── application.py   # Application control
│   │   └── validation.py    # Input validation
│   ├── ai/                  # AI integration for intelligent automation
│   ├── security/            # Security validation and threat detection
│   ├── voice/               # Voice control integration
│   ├── vision/              # Computer vision for screen automation
│   └── workflow/            # Workflow composition and management
├── tests/                   # Comprehensive test suite
│   ├── property_tests/      # Property-based testing
│   ├── integration/         # Integration tests
│   └── security/            # Security validation tests
├── development/             # Project management
│   ├── TODO.md             # Task tracking
│   └── tasks/              # Detailed task specifications
└── pyproject.toml          # Python project configuration

Key Design Patterns

Functional Programming

• Immutable Data Structures: All events and state transitions are immutable
• Pure Functions: Business logic separated from side effects
• Function Composition: Pipeline-based data transformation
• Either Monad: Functional error handling without exceptions

Design by Contract

• Preconditions: Input validation with clear error messages
• Postconditions: Output guarantees and state verification
• Invariants: System constraints maintained throughout execution
• Contract Verification: Automated testing of all contracts

Security Framework

• Defense in Depth: Multiple validation layers
• Input Sanitization: Comprehensive threat detection
• Permission System: Fine-grained access control
• Audit Logging: Complete operation traceability

🧪 Testing

Test Suite Overview

• Comprehensive Test Cases: Focused coverage of computer automation functionality
• Property-Based Testing: Focused hypothesis-driven behavior validation for core automation features
• Integration Testing: End-to-end macro execution and key integration points
• Security Testing: Injection prevention and boundary validation for automation control

Running Tests

# Full test suite with coverage
uv run pytest --cov=src --cov-report=term-missing

# Property-based testing
uv run pytest tests/property_tests/ -v

# Security validation
uv run pytest tests/security/ -v

# Integration tests
uv run pytest tests/integration/ -v

Test Categories

• Unit Tests: Core engine, types, and command validation for precise computer control
• Integration Tests: KM client integration and event system, validating the end-to-end control flow
• Property Tests: System behavior across input ranges for automation reliability
• Security Tests: Injection prevention and input validation for safe computer control

🔒 Security

Given its role in direct computer control, the Keyboard Maestro MCP Server incorporates a robust security framework.

Security Features

• Multi-Level Validation: 5 security levels from Minimal to Paranoid
• Injection Prevention: Script, command, path traversal, and SQL injection protection
• Input Sanitization: Comprehensive threat detection and neutralization
• Permission Boundaries: Fine-grained access control system
• Audit Logging: Complete operation traceability

Security Levels

Level	Description	Use Case
MINIMAL	Basic validation only	Development and testing
STANDARD	Standard security measures	Most production environments
STRICT	Enhanced validation	Security-sensitive environments
PARANOID	Maximum security	High-security production systems

Threat Categories Protected Against

1. Script Injection: JavaScript, AppleScript, shell command injection
2. Command Injection: System command execution prevention
3. Path Traversal: File system access restriction
4. SQL Injection: Database query protection
5. Macro Abuse: Prevention of malicious macro execution that could compromise computer control

📊 Performance

Optimized for responsive client-driven computer automation.

Performance Targets

• Engine Startup: <10ms
• Command Validation: <5ms per command
• Macro Execution: <100ms overhead for typical automation commands executed via the MCP client
• Trigger Response: <50ms
• Memory Usage: <50MB peak

Optimization Features

• Connection Pooling: Reuse KM connections
• Intelligent Caching: Cache macro definitions and validation results
• Async Processing: Non-blocking operation execution
• Resource Management: Automatic cleanup and memory management

🔧 Development

Development Setup

# Install development dependencies
uv sync --group dev

# Install pre-commit hooks
pre-commit install

# Run code quality checks
uv run ruff check src tests
uv run ruff format src tests
uv run mypy src

# Run all tests
uv run pytest

Code Quality Standards

• Type Safety: 100% type coverage with mypy
• Code Formatting: Ruff format with 88-character line length
• Linting: Ruff with security-focused rules
• Documentation: Comprehensive docstrings and contracts
• Test Coverage: >95% coverage target

Contributing Guidelines

1. Follow ADDER+ Architecture: Implement all advanced techniques
2. Maintain Type Safety: Use branded types and contracts
3. Add Property Tests: Test behavior across input ranges
4. Update Documentation: Keep README and task files current
5. Security Review: Validate all security boundaries

📚 Documentation

Additional Resources

• CLAUDE.md: Comprehensive development guidelines
• TESTING.md: Test status and execution guide
• TODO.md: Project task tracking
• Task Files: Detailed implementation specifications in development/tasks/

API Documentation

• MCP Protocol: Built on FastMCP framework
• Type System: Branded types with comprehensive validation
• Error Handling: Structured error responses with recovery suggestions
• Logging: Structured logging with correlation IDs

🤝 Support

Getting Help

• GitHub Issues: Bug reports and feature requests
• Documentation: Comprehensive guides and API reference
• Error Messages: Detailed error information with recovery suggestions
• Logging: Detailed execution traces for debugging

Known Limitations

• macOS Only: Requires macOS and Keyboard Maestro
• KM Dependencies: Full functionality requires Keyboard Maestro 10.0+
• Accessibility: May require accessibility permissions for some operations to enable full computer control
• Performance: Complex macros may exceed timing targets

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Anthropic: For Claude and MCP framework
• Keyboard Maestro: For the powerful automation platform
• FastMCP: For the excellent Python MCP framework
• Hypothesis: For property-based testing capabilities

---

Version: 1.0.0
Last Updated: 2025-06-30
Minimum Requirements: macOS 10.15+, Python 3.10+, Claude Desktop