karabiner-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
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.
Average 4.2/5 across 8 of 8 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It adds that the switch 'takes effect immediately,' which is a useful side-effect detail. However, it does not mention persistence, error handling, or any impact on other profiles, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the first sentence immediately stating the action and target. Every word earns its place; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the core purpose, the prerequisite step, and the immediate effect. An output schema exists to document return values, so the description need not repeat those. Minor gaps like out-of-range behavior are not critical for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains 'profile_index' as the 0-based index and points to list_profiles. The tool description repeats this guidance ('Use list_profiles first') but does not add new semantic information beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Switch') plus a clear resource ('the active Karabiner-Elements profile'). It distinguishes from sibling tools like list_profiles, which lists profiles, and rule-editing tools, which operate on rules rather than profiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly instructs to 'Use list_profiles first to see available profiles and their indices,' giving a clear prerequisite step. It does not discuss exclusions or alternatives beyond this, but the guidance is specific and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full disclosure burden and does well by explaining the persistent effect on karabiner.json: disabling adds 'enabled: false', enabling removes the flag. It does not cover error conditions or profile-specific behavior, but the core mutation semantics are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two crisp sentences with front-loaded action. Every sentence earns its place: the first states the purpose, the second provides essential behavioral detail about the JSON flag mechanics without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description sufficiently covers the tool's behavior, and since an output schema exists, return values need no explanation. Minor gap: it does not mention how profile_index affects the toggle, but the schema covers that parameter, leaving only a small completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all three parameters with clear descriptions. The tool description adds no parameter-specific meaning beyond the schema, which is the expected baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb pair ('Enable or disable') and clearly identifies the target resource ('installed rule'). It effectively distinguishes from sibling tools like add_rule, remove_rule, and edit_rule by focusing on the enabled state mutation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for toggling rule state, but it does not explicitly contrast with edit_rule or state when not to use it. Context is clear, but there are no exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It explicitly reveals the side effect of updating both the asset file and karabiner.json, and implies partial update behavior via 'Only pass the parameters you want to change.' It does not cover error handling or reversibility, but the key mutation behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, with the primary action stated first, followed by the side effect and a usage tip. It is organized into two short paragraphs, and every sentence adds value without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides essential context for a complex mutation tool: its purpose, the files it modifies, the partial-update model, and a recommended pre-step. It does not enumerate all potential constraints, but the schema covers parameter specifics. Overall, it is sufficiently complete for an AI agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter clearly stating 'None = keep current' or 'Pass [] to clear.' The description's general rule about passing only changed parameters reinforces these semantics but does not add per-parameter information. Since schema coverage is high, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Edit an existing rule' with a specific verb and resource, clearly distinguishing it from sibling tools like add_rule, toggle_rule, and remove_rule. It also specifies that it updates both the asset file and karabiner.json, which adds precision to the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear usage recommendation: 'To see a rule's current configuration, use list_rules first.' It also instructs to 'Only pass the parameters you want to change,' which operationalizes the tool. It does not explicitly contrast with add_rule or toggle_rule, but the sibling names make this implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It does not explicitly state the operation is read-only, but the verb 'List' implies no mutation. It adds useful context about what is returned (rule counts, current selection), but lacks explicit statements about side-effects or edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the main purpose, and each sentence adds value. It is efficient with no redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity, an output schema, and zero parameters, the description covers the essential details: what it lists and what extra information it shows. It could mention read-only behavior explicitly, but overall it is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100%. No parameter explanation is needed; the description adds no parameter detail, but the baseline of 4 for 0 parameters is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb 'List' and specifies the resource ('all Karabiner-Elements profiles') plus a distinct detail ('with their rule counts'). It also states it shows the currently selected profile, making the tool's purpose clear and differentiating it from the sibling list_rules (which lists rules).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly points to select_profile as the tool to switch the active profile, implying list_profiles is for reviewing profiles rather than changing them. It does not provide exclusions for other siblings, but for a simple listing tool, this guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses side effects: writes to an asset file and installs in karabiner.json, and notes auto-reload behavior. This goes beyond the schema. However, it doesn't mention potential pitfalls like rule conflicts or whether the operation is reversible, but the core behavioral traits are sufficiently transparent for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core action, followed by behavioral notes and then examples. It is somewhat long, but every sentence earns its place—the examples specifically illustrate parameter combinations that would otherwise be unclear. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's high complexity (17 parameters) and no annotations, the description covers the essential mechanics (file writes, installation, auto-reload), provides usage guidance, and gives practical examples. An output schema exists, so return values are handled elsewhere. The only minor gap is not discussing how this interacts with existing rules on the same keys, but overall it is sufficiently complete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for all 17 parameters (100% coverage), so the baseline is 3. The description adds value by giving real usage examples that tie parameters together, such as from_key_code='caps_lock', to_key_code='escape', and combining to_key_code with to_if_alone_key_code for tap-vs-hold behavior. This contextualizes parameters beyond their individual schema definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Create and install a new Karabiner-Elements rule.' It clearly differentiates from sibling tools by stating it writes to an asset file AND installs in karabiner.json for immediate effect, which is distinct from listing, toggling, removing, or editing rules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage guidance for parameter selection: '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).' It also provides concrete examples for various scenarios, which helps the agent choose appropriate parameters. It doesn't explicitly contrast with sibling tools like edit_rule, but the intent to create is clear from the first sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It specifies the exact return fields (description, enabled/disabled status, installation state, source asset file) and notes the ordering rule (first match wins). This goes beyond a generic 'list' statement, though it could be more explicit about being a non-mutating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, stating the core purpose in the first sentence and then adding return details in two short paragraphs. Every sentence adds value, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, full schema coverage, and the presence of an output schema, the description provides sufficient context for correct invocation. It explains what is returned, the ordering, and the optional parameters' semantics, making it complete for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage of both parameters (profile_index and include_available) with clear descriptions. The tool description does not add significant meaning beyond what the schema offers, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'Karabiner-Elements complex modification rules for a profile,' making the tool's purpose unambiguous. It also distinguishes from siblings like 'list_profiles' by targeting rules within a profile, and from CRUD tools like 'add_rule' and 'remove_rule.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on what the tool does and what it returns, implying when to use it (e.g., inspecting rules in a profile). It does not explicitly exclude alternatives, but the sibling tool names make the differences obvious. The mention of priority order adds useful domain context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the key behavioral trait that the asset file is preserved by default, allowing re-addition later, and clarifies the scope 'all profiles'. This adds meaningful context beyond the obvious removal action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences: the first states the core purpose, the second explains a critical default behavior. No redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with full schema coverage and an output schema, the description provides essential context about default behavior and reversibility. It is sufficient for an agent to understand the tool's scope and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema already provides detailed descriptions for both parameters (100% coverage), including the default for also_delete_asset. The description's mention of the asset preservation aligns with the schema but does not add additional parameter-level information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action 'Remove a rule from karabiner.json (all profiles)', identifying both the verb and resource, and distinguishing it from sibling tools like add_rule, toggle_rule, and edit_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for the default behavior (asset preservation) and references add_rule as an alternative for re-adding, but does not explicitly state when-not-to-use in favor of toggle_rule or edit_rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It appropriately indicates this is a search operation (no side effects) and adds valuable context about Karabiner-specific naming conventions with examples. It does not describe output format or pagination, but the output schema fills that gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: it states the purpose in the first sentence, provides usage guidance in the second, and uses examples for clarification. Every sentence earns its place, with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple search tool with fully documented parameters and an output schema, the description is complete. It covers what the tool does, why it exists, and provides critical domain-specific naming examples. No missing context for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both query and category well-documented. The description does not add new parameter semantics beyond what the schema provides, though the key-code examples help illustrate the expected domain. Baseline score of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a search for valid Karabiner-Elements key codes and modifiers. It uses a specific verb ('search'), names the resource, and distinguishes it from rule-management siblings by explaining its role in preparing key_code strings for add_rule/edit_rule.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Call this before add_rule or edit_rule to find the correct key_code string.' This provides direct contextual guidance and implicitly differentiates it from alternative tools like list_rules or toggle_rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![karabiner-mcp MCP server](https://glama.ai/mcp/servers/jason-weddington/karabiner-mcp/badges/card.svg)](https://glama.ai/mcp/servers/jason-weddington/karabiner-mcp)

Score Badge

Copy to your README.md:

[![karabiner-mcp MCP server](https://glama.ai/mcp/servers/jason-weddington/karabiner-mcp/badges/score.svg)](https://glama.ai/mcp/servers/jason-weddington/karabiner-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jason-weddington/karabiner-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server