Skip to main content
Glama
uhk-mcp

uhk-mcp

by RyanCwynar

uhk-mcp

Configure an Ultimate Hacking Keyboard by describing what you want.

uhk-mcp is an MCP server and a CLI that read, edit and write the keyboard's user configuration over USB. Connect it to Claude (or any MCP client) and ask for things like:

  • "Make the Caps Lock position Escape on tap and Ctrl on hold."

  • "Add a macro that types my email address and put it on Fn2+E."

  • "Give me a Fn3 layer with arrow keys on HJKL and media keys on the number row."

  • "Copy my QWERTY keymap to a new one called GAM and turn off the mod layer key in it."

The model reads your current layout, plans the edits, and sends them in one validated write. Every write backs up the previous config first.

It is built on Agent's own packages (uhk-common for the config format, uhk-usb for the device protocol), pulled in as a git submodule pinned to an Agent release. It does not reimplement either.

Unofficial. Not affiliated with Ultimate Gadget Laboratories.

Status

Tested on a UHK 80 with firmware 18.0.3 and Agent 11.0.0 (user config v15) on Linux. The UHK 60 should work through the same code path but is untested.

Related MCP server: Morningstar MIDI MCP Server

Install

Requires Node 20+, git, and USB access to the keyboard (on Linux, install Agent's udev rules once, the same ones Agent asks for).

git clone --recurse-submodules https://github.com/RyanCwynar/uhk-mcp.git
cd uhk-mcp
npm run setup        # builds the Agent packages it depends on

Add to Claude

Claude Code:

claude mcp add uhk -s user -- /path/to/uhk-mcp/bin/uhk-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "uhk": { "command": "/path/to/uhk-mcp/bin/uhk-mcp" }
  }
}

Close Agent before using it. Agent holds the keyboard's USB interface while it is open, and the server refuses to run while it detects Agent.

Tools

Tool

What it does

uhk_overview

Keymaps and their layers, macros, host connections, all scalar settings

uhk_layer

Every key on a layer as keyName = action

uhk_macro

One macro's actions

uhk_reference

Syntax for actions and ops

uhk_apply

Apply a list of edits in one write (supports dry_run)

uhk_run_command

Run a smart macro command live, without saving

uhk_backups / uhk_restore

List and restore backups

Key names and actions

Keys are physical positions, named after what the factory QWERTY layout puts there: left:Q, left:Mouse (the Caps Lock position), right:Enter, right:Fn2. Modules: left, right, keyCluster, trackball, trackpoint, touchpad.

Actions are short strings:

Ctrl+Shift+T          chord
Esc/lctrl             tap Escape, hold Ctrl
Space/fn              tap Space, hold Fn layer
layer:fn2/toggle      toggle a layer
keymap:QWM            switch keymap
macro:My Macro        play a macro
mouse:leftClick       mouse action
host:Laptop           switch host connection (UHK 80)
Mute  Vol+  Play/Pause

Macros are lists like ["text:hello", "delay:100", "tap:Enter", "cmd:switchKeymap QWM"]. cmd: takes smart macro commands, so anything the firmware's macro language can do is available. Raw Agent JSON is accepted anywhere a string is.

Run uhk reference for the full list.

CLI

uhk overview
uhk layer QWR fn
uhk set-key --dry-run QWR base left:Mouse Esc/lctrl
uhk apply ops.json          # JSON list of ops, same as uhk_apply
uhk run "switchKeymap QWM"
uhk backups
uhk restore <file.bin>

UHK_CONFIG_FILE=config.bin uhk ... edits a binary config file instead of the keyboard.

Safety

Each write:

  1. reads the live config and saves it to ~/.local/state/uhk-mcp/backups/

  2. applies all ops to a copy (if any op fails, nothing is written)

  3. serializes with Agent's serializer and checks that the result decodes back to the same config

  4. writes it, then reads it back from the keyboard and compares

Why

UHK's configuration is rich (layers, secondary roles, macros with a scripting language), and Agent is a good editor for it. Describing an outcome in plain language and having it applied is a different, faster workflow for large changes. This project is meant as a working proposal for an official scripting/MCP interface in Agent.

License

Agent's license applies (see LICENSE): use with Ultimate Hacking Keyboards only, modified versions must ship with source, license kept verbatim. Ultimate Hacking Keyboard is a registered trademark of Ultimate Gadget Laboratories Kft.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Turns a real USB HID device — a Raspberry Pi Pico 2 running open-source firmware — into MCP tools (move, click, drag, type, key combos, scroll) for any MCP client. Includes a --mock mode to try every tool with no hardware.
      17
      61 PyPI
      16
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables natural language interaction with Unfolded Circle Remote 3/Remote Two for configuration, button mapping, UI editing, and backup/restore.
      41
      7
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an AI agent to read and configure OpenDeck stream controller setups through natural language, covering keys, dials, profiles, Multi and Toggle Actions, app-based profile switching, and plugin management. Every change is staged, previewed as a diff, applied only after confirmation, and backed up so it can be undone.
      33
      74 PyPI
      1
      MIT