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

Related MCP server: macos-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