karabiner-mcp
Provides tools to manage Karabiner-Elements keyboard remapping rules on macOS, including searching key codes, adding/editing/removing/toggling rules, and switching profiles.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@karabiner-mcp Remap Caps Lock to Escape"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Find Karabiner key code names (e.g. "enter" → |
| List all rules in the current profile with enabled/disabled status |
| Create a new remapping rule |
| Modify an existing rule |
| Delete a rule (with optional asset cleanup) |
| Enable or disable a rule |
| Show all Karabiner profiles |
| 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 checkLicense
Available Tools
8 toolsadd_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
Scored across 8 tools
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.
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.
8 tools is well-scoped for managing Karabiner rules and profiles, covering CRUD and auxiliary operations without bloat or thinness.
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
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceA lightweight MCP server that bridges AI agents and macOS, enabling automation of file navigation, application control, UI interaction, browser automation, and system operations.244MIT
- AlicenseBqualityDmaintenanceMCP server that enables AI to fully control macOS — mouse, keyboard, terminal, screenshots, window management, UI element detection, and provides AI-optimized information reporting.3621 npmMIT
- AlicenseAqualityDmaintenanceA local MCP server that exposes macOS automation actions (AppleScript + CLIs) as tools, enabling MCP clients on your Mac to control apps, system settings, and more.39MIT
- FlicenseNot gradedqualityDmaintenanceEnterprise-grade macOS MCP server that gives AI agents eyes, hands, and a terminal, enabling screen capture, mouse/keyboard control, shell commands, and file operations.-