uhk-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 onAdd to Claude
Claude Code:
claude mcp add uhk -s user -- /path/to/uhk-mcp/bin/uhk-mcpClaude 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 |
| Keymaps and their layers, macros, host connections, all scalar settings |
| Every key on a layer as |
| One macro's actions |
| Syntax for actions and ops |
| Apply a list of edits in one write (supports |
| Run a smart macro command live, without saving |
| 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/PauseMacros 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:
reads the live config and saves it to
~/.local/state/uhk-mcp/backups/applies all ops to a copy (if any op fails, nothing is written)
serializes with Agent's serializer and checks that the result decodes back to the same config
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Floor plans as code: compile, lint and repair ArchLang (.arch) floor plans to SVG, DXF and PDF.
Write and check ConsoleMouse profile files: format, validator, plain-language preview, import code.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Create, edit, validate, inspect and export parametric 3D models in your confBuild account.
Related MCP Servers
- AlicenseAqualityBmaintenanceTurns 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.1761 PyPI16MIT
- AlicenseCqualityDmaintenanceEnables configuring Morningstar MIDI foot controllers using natural language, including switch mapping, MIDI CC lookup, conflict detection, and USB programming.92MIT
- AlicenseBqualityBmaintenanceEnables natural language interaction with Unfolded Circle Remote 3/Remote Two for configuration, button mapping, UI editing, and backup/restore.417MIT
- AlicenseAqualityBmaintenanceEnables 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.3374 PyPI1MIT