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
-
Clone the repository:
git clone https://github.com/anthropics/keyboard-maestro-mcp.git cd keyboard-maestro-mcp -
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]" -
Configure Keyboard Maestro:
- Enable "Web Server" in Keyboard Maestro preferences
- Set port to 4490 (default)
- Grant accessibility permissions if prompted
-
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 UUIDtrigger_value(optional string): Parameter to pass to macromethod(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 groupenabled_only(boolean): Only return enabled macrossort_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 namevalue(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 contentscope(string): Search scope (name_only, name_and_group, full_content, metadata_only)action_categories(optional string): Filter by action typescomplexity_levels(optional string): Filter by complexity levelsmin_usage_count(integer): Minimum execution count filtersort_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 analyzeinclude_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 groupinclude_enabled_count(boolean): Include count of enabled macrossort_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 synchronizationkm_stop_realtime_sync: Stop real-time synchronizationkm_sync_status: Get synchronization status with metricskm_force_sync: Force immediate synchronization
Resources
km://server/status: Server status and configurationkm://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
- Script Injection: JavaScript, AppleScript, shell command injection
- Command Injection: System command execution prevention
- Path Traversal: File system access restriction
- SQL Injection: Database query protection
- 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
- Follow ADDER+ Architecture: Implement all advanced techniques
- Maintain Type Safety: Use branded types and contracts
- Add Property Tests: Test behavior across input ranges
- Update Documentation: Keep README and task files current
- 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