Deckhand MCP Server

Why Deckhand?

Linux has Stream Deck tools, but most of them either look dated or make you fight the workflow. Deckhand is built to feel like the Windows app people love, minus the Windows: a clean three-panel editor, drag-and-drop everything, instant feedback on the real deck, and sensible behaviour when things go wrong.

• Looks and flows like a modern desktop app. Dark theme, purposeful micro-animations, undo/redo for everything, a command palette, no sideways scrolling.

• Runs great on Wayland. Keys are injected through uinput and window tracking uses KWin, so nothing depends on X11 tools.

• Zero fragile dependencies. Only PyQt6 and the hidapi system library. The USB driver, the MCP server and the D-Bus bridge are written in plain Python.

• Safe by design. Corrupt data is quarantined, never overwritten. Every edit is undoable. AI agents ask before they run anything.

Related MCP server: streamdeck-mcp

Features

Layout and editing

• Three-panel editor: searchable action list, a live deck canvas, and an inspector for the selected key.

• Drag and drop: drop actions on keys, drag keys to rearrange (Ctrl-drag to copy), drop an image onto a key to use it as its icon, or drag a key onto a page tab to move it there.

• Pages, folders and profiles with import/export, duplicate, reorder and copy-between-profiles.

• Template gallery with ready-made pages: Media, Streaming, Productivity, Developer, System monitor.

• Command palette (Ctrl+K) to jump to any profile, page, folder, action or command.

• Full undo/redo, copy/paste/duplicate keys, keyboard navigation, F1 shortcut cheat sheet.

• Modern colour picker (not the 1990s dialog): saturation square, hue strip, hex field, palette and recents.

Actions

• Hold actions: a quick tap runs the main action, holding (configurable) runs a second one.

• State-aware keys: Mic Mute, Mute and Play/Pause follow the real system state (even when changed elsewhere). Any other key can get an alternate "active" look that toggles on press.

Now Playing with album art

Works with any MPRIS player. Spotify and YouTube Music (desktop apps and browser tabs) are handled explicitly: low-resolution thumbnails are upgraded to full covers, YouTube video thumbnails are used as a fallback, downloads happen in the background and are cached, and a failed download never stalls the key.

Wallpapers, including animated ones

Spread one image across the whole deck, aligned across the physical gaps between keys. Fill / Fit / Stretch, zoom, position and darken controls. Animated GIF and WebP wallpapers play on the deck at 5-20 fps with smart frame pacing (a slow deck drops frames instead of lagging) and bounded memory.

Auto-switch profiles by active window

Map an app or a window title (plain text or re: regex) to a profile; the first matching rule wins. On KDE Plasma this uses a tiny KWin script that is loaded only while the feature is on, and nothing leaves your computer.

AI agents (MCP) built in

Deckhand ships an MCP server so Claude, Codex, Gemini CLI, Cursor, Windsurf, VS Code, Zed, opencode and any other MCP-capable agent can design and manage your deck.

deckhand mcp install        # connects every agent app it finds, one command

• 34 tools: read the layout, build pages and keys, set icons and wallpapers, manage profiles, take screenshots to verify their own work, undo, and more. Batch edits are a single undo step.

• Three access levels (Read-only, Edit layout, Full control) set in the Agents dialog; the default is Edit layout.

• Approval prompts: tools that run things on your computer (press_key, run_action) show exactly what will run and wait for your click.

• Private by construction: the server listens on a user-only Unix socket, nothing is exposed on the network.

Reliability

• Diagnosed device states: not plugged in, held by another program (with a Close it button), missing USB permission (with the exact fix), unsupported model, missing hidapi. Offline editing always works and the deck is filled the moment it appears.

• Branded loading screen that ends as soon as the deck is found or a clear problem is known.

• Never loses data: corrupt files are copied aside, saves retry on failure, a daily automatic backup is kept, and Preferences has Back up, Restore (with a safety copy) and Save diagnostics.

• Fail-soft rendering: a broken key becomes a warning tile, never a crash.

Quality of life

Night dimming schedule, idle sleep, press animation, remembered window layout, start-minimized tray mode with autostart, single-instance guard, hold-time setting, per-action friendly error messages ("'konsole' isn't installed (Arch package: konsole)").

Supported hardware

Multiple decks are detected; pick which one to use from the status chip.

Install

Requirements

• Linux with Python 3 (developed and tested on Python 3.14, CachyOS / Arch, KDE Plasma 6, Wayland)

• PyQt6 (with QtSvg, QtNetwork and QtDBus)

• The hidapi system library

# Arch / CachyOS
sudo pacman -S python-pyqt6 hidapi
# Other distros: install PyQt6 (with QtSvg/QtNetwork/QtDBus) and hidapi from your package manager;
# package names vary, and only Arch has been tested.

Get it

Arch / CachyOS (installs the dependencies, launcher, menu entry, icon and the udev rules for you):

git clone https://github.com/ProfetGit/deckhand.git
cd deckhand/packaging/arch && makepkg -si

Any distro with PyQt6 and hidapi installed: pipx install --system-site-packages git+https://github.com/ProfetGit/deckhand.git (then add the udev rules below).

A Flatpak manifest is in packaging/flatpak/. It builds and starts, but actions that run host tools do not work inside the sandbox; prefer the options above.

From a checkout (per-user, no root):

git clone https://github.com/ProfetGit/deckhand.git
cd deckhand
./scripts/install.sh        # per-user launcher, app-menu entry and icon (no root)
deckhand                    # or start it from your app menu

You can also run it straight from the checkout: python3 -m deckhand.

One-time permissions

USB access to the deck. If Deckhand reports a permission problem it shows the exact fix. The rule is:

printf '%s\n' 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", TAG+="uaccess"' \
              'KERNEL=="hidraw*", ATTRS{idVendor}=="0fd9", TAG+="uaccess"' \
  | sudo tee /etc/udev/rules.d/70-deckhand-streamdeck.rules >/dev/null \
  && sudo udevadm control --reload-rules && sudo udevadm trigger

Sending keystrokes (hotkeys, media keys) uses /dev/uinput. Preferences shows a one-line rule if it is not accessible:

echo 'KERNEL=="uinput", SUBSYSTEM=="misc", TAG+="uaccess", OPTIONS+="static_node=uinput"' \
  | sudo tee /etc/udev/rules.d/70-deckhand-uinput.rules >/dev/null \
  && sudo udevadm control --reload-rules && sudo udevadm trigger

Only one program can control a Stream Deck at a time. Close the Elgato software, StreamController, streamdeck-ui or OpenDeck first; Deckhand will tell you if one of them is holding the deck.

Usage

1. Plug in your deck and start Deckhand. The deck's keys appear in the editor.

2. Drag an action from the left panel onto a key (or double-click it to add it to the selected key).

3. Fine-tune the key in the panel below: icon, title, colours, the action's settings, an optional hold action and an optional "active" look.

4. Use Ctrl+K for everything else.

Closing the window keeps Deckhand running in the tray so your keys keep working; quit from the tray menu.

Keyboard shortcuts

AI agents: setup details

deckhand mcp status         # which agent apps were found and which are connected
deckhand mcp install        # connect all detected apps (or name one: claude-code, codex, gemini, ...)
deckhand mcp uninstall      # remove it again
deckhand mcp config         # print a JSON snippet for any other agent

The agent's config simply starts deckhand mcp, a tiny stdio bridge that launches the app if needed and talks to it over a private Unix socket. Config files are merged (never overwritten) and backed up first. In the app, open Agents to switch access levels, see connected agents and revoke "allow for this session" approvals.

How it works

deckhand/
  hardware.py     USB HID driver (ctypes over hidapi), device scan and the reconnect state machine
  engine.py       central controller: profiles, navigation, undo, device sync, key dispatch
  render.py       key renderer (one code path for the deck and the editor)
  actions.py      action registry and executors      templates.py  ready-made pages
  wallpaper.py    wallpaper slicing and animation    autoswitch.py KWin script + D-Bus bridge
  sysinfo.py      live system state (mute, MPRIS, GPU)
  agentapi.py     the agent-facing tool set          mcp_server.py MCP over a Unix socket
  mainwindow.py, widgets.py, inspector.py, ...        the Qt interface
tests/            headless test suites (UI, engine, MCP, installer, resilience, animation...)
docs/             README images and the script that regenerates them

Data lives in ~/.config/deckhand/ (profiles.json, settings.json, imported icons, backups/, errors.log). Profiles are plain JSON.

Development

pip install -r requirements.txt        # PyQt6 and Pillow (tests and image generation)

python3 tests/smoke.py                 # engine, UI, drag and drop, key states
python3 tests/test_mcp.py              # MCP server end to end through the real stdio bridge
python3 tests/test_install.py          # agent installer (sandboxed HOME)
python3 tests/test_resilience.py       # corrupt data, device states, loading screen
python3 tests/test_anim.py             # animated wallpapers
python3 tests/test_autoswitch.py       # window rules and the D-Bus path
python3 tests/test_features.py         # hold actions, timers, pages, templates, backups
python3 tests/test_nowplaying.py       # Now Playing, Spotify / YouTube Music art
python3 tests/test_timer.py            # timer sound, auto-reset and custom sounds
python3 tests/test_buttons.py          # button hover glow, pointer cursor
python3 docs/make_assets.py            # regenerate the images in docs/images

All tests run headless (QT_QPA_PLATFORM=offscreen) in throwaway config directories, so they never touch your real profiles or hardware.

Contributions are welcome. Please open an issue first for larger changes, keep new actions self-contained in actions.py (registry entry plus executor), and add tests next to the behaviour you change.

Troubleshooting

Roadmap

Ideas that are not built yet: multi-select keys, a macro recorder, a screen eyedropper in the colour picker, more deck models, and window-aware switching on desktops other than KDE.

License and notices

Released under the MIT License.

Deckhand is an independent project. It is not affiliated with, endorsed by or sponsored by Elgato or Corsair. "Stream Deck" is a trademark of its respective owner and is used here only to describe compatible hardware. Spotify and YouTube Music are trademarks of their owners; Deckhand only displays cover art that your own media player publishes.