Skip to content
Back to search

cytrence-kiwi-mcp

MCP server that lets AI agents see and control a computer through a Cytrence Kiwi USB-C KVM (HDMI capture + USB keyboard/mouse emulation).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/theboroer--cytrence-kiwi-mcp/badge.svg)](/listings/theboroer--cytrence-kiwi-mcp)

HTML

<a href="/listings/theboroer--cytrence-kiwi-mcp"><img src="/api/listings/theboroer--cytrence-kiwi-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install
npm run build

Claude Code

claude mcp add kiwi -e KIWI_INVERT_SCROLL=1 -- node /absolute/path/to/cytrence-kiwi-mcp/dist/index.js

Claude Desktop and other MCP clients

{
  "mcpServers": {
    "kiwi": {
      "command": "node",
      "args": ["/absolute/path/to/cytrence-kiwi-mcp/dist/index.js"],
      "env": { "KIWI_INVERT_SCROLL": "1" }
    }
  }
}

`KIWI_INVERT_SCROLL=1` is for targets with natural scrolling (the macOS default). Leave it out for Windows and most Linux targets.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 248 lines
  1. # cytrence-kiwi-mcp
  2. An [MCP](https://modelcontextprotocol.io) server that lets AI agents see and drive a second computer
  3. through a [Cytrence Kiwi](https://www.cytrence.com/product-page/cytrence-kiwi) USB-C KVM. The agent gets
  4. the target's screen through the Kiwi's HDMI capture, and clicks, scrolls, and types through the Kiwi's USB
  5. keyboard and mouse emulation.
  6. > **Work in progress:** this is still being actively worked on. Tools, settings, and behavior may change
  7. > between updates, so pull often and check back here when something stops working.
  8. The target needs no software, drivers, or network access. To it, the Kiwi is just a monitor, keyboard,
  9. and mouse. That makes this useful for BIOS screens, freshly installed machines, locked-down boxes, and
  10. anything else you can't install an agent on.
  11. The serial protocol isn't documented by Cytrence. It was reverse-engineered from the official app and
  12. firmware; see [docs/PROTOCOL.md](docs/PROTOCOL.md) for the full write-up.
  13. > **Heads-up:** anything connected to this server has full keyboard and mouse control of the target
  14. > computer. Only point it at machines you're happy for an agent to operate.
  15. ## Requirements
  16. - A Cytrence Kiwi, with its host USB-C port plugged into the machine running this server, and the target's HDMI and USB connected to the Kiwi.
  17. - Node.js 20 or newer.
  18. - ffmpeg on your `PATH` (`brew install ffmpeg`).
  19. - The official Cytrence Kiwi app **closed** while the server is talking to the device, since both need the same serial port. The server lets go of the port after 30 s of inactivity, so you can switch back and forth.
  20. - On macOS, Camera permission for whatever launches the server (Terminal, iTerm, Claude Desktop...): System Settings > Privacy & Security > Camera.
  21. Tested on macOS (Apple silicon) with a Kiwi v1.1/B on firmware 2.10, driving a macOS target. The Linux
  22. (v4l2) and Windows (dshow) capture paths are implemented but untested.
  23. ## Setup
  24. ```sh
  25. npm install
  26. npm run build
  27. ```
  28. ### Claude Code
  29. ```sh
  30. claude mcp add kiwi -e KIWI_INVERT_SCROLL=1 -- node /absolute/path/to/cytrence-kiwi-mcp/dist/index.js
  31. ```
  32. ### Claude Desktop and other MCP clients
  33. ```json
  34. {
  35. "mcpServers": {
  36. "kiwi": {
  37. "command": "node",
  38. "args": ["/absolute/path/to/cytrence-kiwi-mcp/dist/index.js"],
  39. "env": { "KIWI_INVERT_SCROLL": "1" }
  40. }
  41. }
  42. }
  43. ```
  44. `KIWI_INVERT_SCROLL=1` is for targets with natural scrolling (the macOS default). Leave it out for
  45. Windows and most Linux targets.
  46. ## Live viewer: watch, help, take over
  47. With the stdio setup above there is nothing to start yourself. The first time the agent uses the
  48. Kiwi, the server starts a live viewer at `http://127.0.0.1:7523/` and the agent passes you the link
  49. once. Open it if you want to watch or help. The viewer closes when the agent's session ends. The
  50. agent can also open it in your browser with `open_viewer`, for example when you ask to watch or
  51. when it needs you to type a password on the target. `device_info` reports the link too.
  52. In the viewer, click the screen to drive the target's mouse, click again to capture your keyboard
  53. (green border), and type and scroll as usual. Shortcuts your own computer grabs first, like cmd+tab
  54. or ctrl+alt+delete, are in the "Send keys" menu. Pick "Custom..." there for any other combo.
  55. "Paste" types your computer's clipboard into the target, one keystroke at a time, so it works
  56. wherever the target's cursor is (login screens and BIOS included). The browser asks for clipboard
  57. permission the first time; if it won't share, you get a box to paste into instead. Only US-keyboard
  58. characters can be typed, so text with curly quotes, accents, or emoji is refused whole, and a
  59. paste is capped at 5000 characters. Long pastes take a while, since every character is a real
  60. keystroke; the agent stays paused until typing finishes. A newline presses Enter.
  61. ### More than one agent session
  62. Only one process can hold the Kiwi's serial port and capture device, so only one session uses the
  63. Kiwi at a time. Whichever session has the viewer port owns the Kiwi. Sessions that never touch the
  64. Kiwi don't claim it, so having the server configured everywhere costs nothing.
  65. When a second session wants the Kiwi:
  66. - if the owner has been idle for 10 minutes (`KIWI_HANDOVER_IDLE_MS`) and nobody has its viewer
  67. open, the Kiwi moves over without asking.
  68. - otherwise the second agent is told the Kiwi is busy and asks you. If you agree, it calls
  69. `take_over`, the first session lets go, and its tools say the Kiwi was taken until it calls
  70. `take_over` itself.
  71. - an open viewer on the first session closes when it loses the Kiwi. Open the new link the agent
  72. gives you.
  73. Only another Kiwi session can ask for a handover: the request is refused from a web page.
  74. ### Running it yourself (`serve`)
  75. If you'd rather keep one server running whatever the agents do, start it on its own:
  76. ```sh
  77. KIWI_INVERT_SCROLL=1 node dist/index.js serve # or: npm run serve
  78. ```
  79. That starts one long-running process on `http://127.0.0.1:7523` with the viewer at `/` and a
  80. streamable HTTP MCP endpoint at `/mcp`. Point the agent at it instead of launching its own:
  81. ```sh
  82. claude mcp add --transport http kiwi http://127.0.0.1:7523/mcp
  83. ```
  84. A stdio session never takes the Kiwi from `serve`. It tells the agent to connect to `/mcp` or ask
  85. you to stop that server. `serve` has to outlive the agent's command, so start it in a terminal you
  86. own or as a login item.
  87. ### Sharing control
  88. You and the agent share the machine. When you click, scroll, or type in the viewer the agent is
  89. paused ("Take over when I use it", on by default), and its input tools return an error telling it
  90. to wait. Once you've sent no input for 15 seconds (`KIWI_AUTO_RESUME_MS`) the agent gets control
  91. back on its own, and the status pill counts down to it. Any input you send, mouse moves included,
  92. resets that countdown. Press "Resume agent" to hand control back sooner. Just moving the mouse over
  93. the viewer does not pause it. A pause from the "Pause agent" button lasts until you press Resume.
  94. The Activity panel (the icon at the top right) lists every agent action as it happens. It starts
  95. hidden to give the screen more room, and the viewer remembers whether you left it open.
  96. If the target's screen isn't 16:9 (most Macs are 16:10), the Kiwi sends its picture centred
  97. between black bars. The server finds those bars and maps clicks to the picture inside them, so
  98. the cursor lands where you or the agent pointed. Clicks on a bar go to the nearest edge of the
  99. screen.
  100. The server only listens on localhost and rejects requests addressed to other hostnames, and only
  101. the viewer page itself can send input. Anything running on your Mac can still reach it, so don't
  102. expose the port to a network.
  103. ## Tools
  104. | Tool | What it does |
  105. | --- | --- |
  106. | `screenshot` | Capture the target screen as a JPEG (1280x720 by default). All coordinates refer to this image. |
  107. | `click` | Click at (x, y); supports right/middle buttons, double and triple clicks, and held modifiers (e.g. `cmd`). |
  108. | `mouse_move` | Move the pointer without clicking (hover). |
  109. | `drag` | Press, move smoothly, release. For selections, sliders, and drag-and-drop. |
  110. | `scroll` | Wheel scroll up/down/left/right over a point. |
  111. | `type_text` | Type text with US-layout keystrokes. `\n` presses Enter and `\t` presses Tab. |
  112. | `press_keys` | Press a key or shortcut: `enter`, `cmd+space`, `ctrl+alt+delete`, `shift+tab`, `f5`... |
  113. | `release_all` | Release every key and button (if something seems stuck). |
  114. | `set_hid_mode` | Switch between normal HID and legacy boot-protocol HID (some BIOS screens need legacy). |
  115. | `device_info` | Live viewer link, Kiwi model, firmware and bootloader versions, ports in use, and recent device log lines. |
  116. | `open_viewer` | Open the live viewer in your browser, unless a viewer tab is already open. |
  117. | `take_over` | Take the Kiwi from another agent session (stdio only, after you agree). |
  118. Every input tool takes an optional `screenshot: true`. It returns a fresh capture once the UI has
  119. settled, which saves the agent a round trip.
  120. ## Configuration
  121. All settings are optional environment variables.
  122. | Variable | Default | Meaning |
  123. | --- | --- | --- |
  124. | `KIWI_SERIAL_PORT` | auto | Serial device. Auto-detects the Kiwi's CH340 (USB `1a86:7523`). |
  125. | `KIWI_BAUD` | `2000000` | Serial baud rate. |
  126. | `KIWI_SERIAL_IDLE_MS` | `30000` | Release the serial port after this much idle time. `0` keeps it open. |
  127. | `KIWI_VIDEO_DEVICE` | auto | Capture device name (macOS/Windows) or `/dev/videoN` (Linux). |
  128. | `KIWI_CAPTURE_SIZE` | `1920x1080` | Capture mode requested from the Kiwi. |
  129. | `KIWI_SCREENSHOT_WIDTH` | `1280` | Width of screenshots sent to the agent (height keeps the aspect ratio). |
  130. | `KIWI_VIDEO_IDLE_MS` | `60000` | Stop the background ffmpeg stream after this much idle time. `0` runs ffmpeg once per screenshot. The stream stays up while a viewer is open. |
  131. | `KIWI_VIDEO_FPS` | `10` (`20` under `serve`) | Frames per second of the background stream. |
  132. | `KIWI_PORT` | `7523` | Viewer port (same as `--port`). Stdio sessions also use it to tell which one has the Kiwi, so give every session the same port. |
  133. | `KIWI_INVERT_SCROLL` | off | Flip scroll direction, for targets with natural scrolling. |
  134. | `KIWI_KEY_DELAY_MS` | `12` | Delay between keyboard reports while typing. |
  135. | `KIWI_SETTLE_MS` | `500` | Wait before the screenshot that follows an action. |
  136. | `KIWI_AUTO_RESUME_MS` | `15000` | After you take over in the viewer, give control back to the agent once you've sent no input for this long. `0` keeps it paused until you press Resume. |
  137. | `KIWI_HANDOVER_IDLE_MS` | `600000` | A session that hasn't used the Kiwi for this long, with no viewer open, hands it to another session without asking. |
  138. | `KIWI_DETECT_BARS` | on | Find black bars around the target's picture and map the mouse inside them. Set to `0` if the target's own screen has black edges that get mistaken for bars. |
  139. | `FFMPEG_PATH` | `ffmpeg` | ffmpeg binary. |
  140. ## Manual testing CLI
  141. The same code paths are available from the shell, which is handy for checking the hardware without an agent:
  142. ```sh
  143. npm run cli -- info
  144. npm run cli -- screenshot shot.jpg
  145. npm run cli -- click 640 360
  146. npm run cli -- scroll down 5 640 360
  147. npm run cli -- key cmd+space
  148. npm run cli -- type "hello world"
  149. npm run cli -- hid-mode normal
  150. ```
  151. After `npm run build` it's also available as `node dist/cli.js ...`.
  152. ## Development
  153. ```sh
  154. npm test # protocol unit tests, anchored on frames captured from real hardware
  155. npm run typecheck
  156. npm run dev # run the MCP server from source with tsx
  157. ```
  158. Source layout:
  159. - `src/protocol.ts`: frame encoding and decoding, CRC-8, HID report builders.
  160. - `src/link.ts`: serial connection (auto-detect, warm-up, write serialization, idle close).
  161. - `src/video.ts`: ffmpeg capture, with a warm MJPEG stream and a one-shot fallback.
  162. - `src/keys.ts`: key names, chords, and the US-layout text map.
  163. - `src/kiwi.ts`: high-level gestures (click, drag, scroll, typing).
  164. - `src/index.ts`: the MCP server.
  165. - `src/cli.ts`: the manual test CLI.
  166. ## Troubleshooting
  167. **"Serial port ... is in use"**
  168. Quit the Cytrence Kiwi app.
  169. **"No Cytrence Kiwi serial port found"**
  170. The Kiwi's host-side USB-C cable isn't connected to this computer, or `KIWI_SERIAL_PORT` points somewhere else.
  171. **Screenshots fail on macOS**
  172. Grant Camera permission to the app that launches the server, then restart that app.
  173. **Scrolling goes the wrong way**
  174. Toggle `KIWI_INVERT_SCROLL`.
  175. **Keys do nothing in a BIOS or boot menu**
  176. Call `set_hid_mode` with `legacy`. Switch back to `normal` once the OS has loaded.
  177. **Wrong characters when typing**
  178. `type_text` assumes the target uses a US keyboard layout.
  179. ## Disclaimer
  180. This is an independent project, not affiliated with or endorsed by Cytrence. It relies on an undocumented
  181. protocol, so a firmware update could break it.
  182. ## License
  183. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.