Karabiner

MCP server for managing Karabiner-Elements keyboard remapping rules on macOS.

Exposes Karabiner configuration as MCP tools so an LLM can search key codes, list/add/edit/remove/toggle rules, and switch profiles — all through natural language.

Tools

Tool	Description
search_key_codes	Find Karabiner key code names (e.g. "enter" → return_or_enter)
list_rules	List all rules in the current profile with enabled/disabled status
add_rule	Create a new remapping rule
edit_rule	Modify an existing rule
remove_rule	Delete a rule (with optional asset cleanup)
toggle_rule	Enable or disable a rule
list_profiles	Show all Karabiner profiles
select_profile	Switch the active profile

Installation

Requires Python 3.13+ and uv. No need to clone the repo — register the server in your Claude config (~/.claude.json) and uvx will install it on first run:

{
  "mcpServers": {
    "karabiner-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/jason-weddington/karabiner-mcp.git",
        "karabiner-mcp"
      ]
    }
  }
}

Then ask Claude things like:

• "Remap Caps Lock to Escape"
• "Make right Option act as Hyper key"
• "When I tap left Shift, type open-paren"
• "Disable the rule called 'Caps Lock to Escape'"

Rule patterns

• Simple remap — one key to another
• Modifier combo — e.g. Cmd+Shift+K to something
• Tap vs hold — different output for tap and hold on the same key
• App-specific — rules scoped to specific applications by bundle ID
• Shell command — trigger a shell command from a key combo

Development

uv run pytest                        # Run tests
uv run pytest --cov=karabiner_mcp    # Tests with coverage
uv run ruff check .                  # Lint
uv run ruff format .                 # Format
uv run mypy src/                     # Type check

License

MIT