Skip to main content
Glama

karabiner-mcp

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

Related MCP server: macos-control-mcp

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

Available Tools

8 tools
add_ruleA

Create and install a new Karabiner-Elements rule.

Writes the rule to an asset file AND installs it in karabiner.json for immediate effect. Karabiner-Elements auto-reloads on file change.

For simple remaps, use to_key_code. For tap-vs-hold, combine to_key_code (held behavior) with to_if_alone_key_code (tap behavior).

Examples:

  • Simple remap (caps->esc): from_key_code="caps_lock", to_key_code="escape"

  • With modifier (ctrl+h->backspace): from_key_code="h", from_mandatory_modifiers=["control"], to_key_code="delete_or_backspace"

  • Tap/hold (caps: tap=esc, hold=ctrl): from_key_code="caps_lock", to_key_code="left_control", to_if_alone_key_code="escape"

  • App-specific: add app_if=['^com.apple.Terminal$']

  • Shell command: from_key_code="f5", to_shell_command="open -a Safari"

Inputs: description (required), app_if, to_keys, device_if, +13 more. Returns: result

edit_ruleA

Edit an existing rule. Updates both the asset file and karabiner.json. Only pass the parameters you want to change.

To see a rule's current configuration, use list_rules first.

Inputs: description (required), app_if, device_if, app_unless, +11 more. Returns: result

list_profilesA

List all Karabiner-Elements profiles with their rule counts.

Shows which profile is currently selected. Use select_profile to switch the active profile.

Inputs: no named parameters. Returns: result

list_rulesA

List Karabiner-Elements complex modification rules for a profile.

Returns each rule's description, enabled/disabled status, whether it's installed in karabiner.json, and its source asset file. Rules are listed in priority order (first match wins in Karabiner).

Inputs: profile_index, include_available. Returns: result

remove_ruleA

Remove a rule from karabiner.json (all profiles).

By default the asset file is preserved so the rule can be re-added later via the Karabiner Settings UI or add_rule.

Inputs: description (required), also_delete_asset. Returns: result

search_key_codesA

Search valid Karabiner-Elements key codes and modifiers.

Call this before add_rule or edit_rule to find the correct key_code string. Key codes are Karabiner-specific identifiers (e.g. 'return_or_enter' not 'enter', 'delete_or_backspace' not 'backspace', 'grave_accent_and_tilde' not '`').

Inputs: query, category. Returns: result

select_profileA

Switch the active Karabiner-Elements profile.

Takes effect immediately. Use list_profiles first to see available profiles and their indices.

Inputs: profile_index (required). Returns: result

toggle_ruleA

Enable or disable an installed rule.

The rule stays in karabiner.json either way — disabling adds 'enabled: false', enabling removes that flag.

Inputs: enabled (required), description (required), profile_index. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct operation: rule lifecycle (add, list, toggle, remove, edit), profile management (list, select), and key code lookup (search). No two tools have overlapping purposes.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in lowercase snake_case (list_rules, add_rule, toggle_rule, remove_rule, edit_rule, list_profiles, select_profile, search_key_codes). No deviations.

    Tool Count5/5

    8 tools is well-scoped for managing Karabiner rules and profiles, covering CRUD and auxiliary operations without bloat or thinness.

    Completeness4/5

    Rule CRUD and profile selection are covered, but there is no tool to reorder rules, which is important given Karabiner's priority-based matching. Minor gap that agents can work around by editing the underlying file.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      A lightweight MCP server that bridges AI agents and macOS, enabling automation of file navigation, application control, UI interaction, browser automation, and system operations.
      244
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      MCP server that enables AI to fully control macOS — mouse, keyboard, terminal, screenshots, window management, UI element detection, and provides AI-optimized information reporting.
      36
      21 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enterprise-grade macOS MCP server that gives AI agents eyes, hands, and a terminal, enabling screen capture, mouse/keyboard control, shell commands, and file operations.
      -