uhk-mcp
by RyanCwynar
README.md
# uhk-mcp
Configure an [Ultimate Hacking Keyboard](https://uhk.io) 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.
## 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).
```sh
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:
```sh
claude mcp add uhk -s user -- /path/to/uhk-mcp/bin/uhk-mcp
```
Claude Desktop (`claude_desktop_config.json`):
```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](https://github.com/UltimateHackingKeyboard/firmware/blob/master/doc-dev/reference-manual.md) 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
```sh
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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues