cytrence-kiwi-mcp
Enables AI agents to drive a Linux target computer through the Kiwi KVM, providing screen capture plus mouse and keyboard control; the Linux v4l2 capture path is implemented but untested.
Enables AI agents to see and control a macOS target computer through the Cytrence Kiwi KVM, including screen capture, mouse movement/clicks/drags/scrolling, and keyboard input/shortcuts.
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.
cytrence-kiwi-mcp
An MCP server that lets AI agents see and drive a second computer through a Cytrence Kiwi USB-C KVM. The agent gets the target's screen through the Kiwi's HDMI capture, and clicks, scrolls, and types through the Kiwi's USB keyboard and mouse emulation.
Work in progress: this is still being actively worked on. Tools, settings, and behavior may change between updates, so pull often and check back here when something stops working.
The target needs no software, drivers, or network access. To it, the Kiwi is just a monitor, keyboard, and mouse. That makes this useful for BIOS screens, freshly installed machines, locked-down boxes, and anything else you can't install an agent on.
The serial protocol isn't documented by Cytrence. It was reverse-engineered from the official app and firmware; see docs/PROTOCOL.md for the full write-up.
Heads-up: anything connected to this server has full keyboard and mouse control of the target computer. Only point it at machines you're happy for an agent to operate.
Requirements
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.
Node.js 20 or newer.
ffmpeg on your
PATH(brew install ffmpeg).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.
On macOS, Camera permission for whatever launches the server (Terminal, iTerm, Claude Desktop...): System Settings > Privacy & Security > Camera.
Tested on macOS (Apple silicon) with a Kiwi v1.1/B on firmware 2.10, driving a macOS target. The Linux (v4l2) and Windows (dshow) capture paths are implemented but untested.
Related MCP server: kvm-auto-mcp
Setup
npm install
npm run buildClaude Code
claude mcp add kiwi -e KIWI_INVERT_SCROLL=1 -- node /absolute/path/to/cytrence-kiwi-mcp/dist/index.jsClaude 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.
Live viewer: watch, help, take over
With the stdio setup above there is nothing to start yourself. The first time the agent uses the
Kiwi, the server starts a live viewer at http://127.0.0.1:7523/ and the agent passes you the link
once. Open it if you want to watch or help. The viewer closes when the agent's session ends. The
agent can also open it in your browser with open_viewer, for example when you ask to watch or
when it needs you to type a password on the target. device_info reports the link too.
In the viewer, click the screen to drive the target's mouse, click again to capture your keyboard (green border), and type and scroll as usual. Shortcuts your own computer grabs first, like cmd+tab or ctrl+alt+delete, are in the "Send keys" menu. Pick "Custom..." there for any other combo.
"Paste" types your computer's clipboard into the target, one keystroke at a time, so it works wherever the target's cursor is (login screens and BIOS included). The browser asks for clipboard permission the first time; if it won't share, you get a box to paste into instead. Only US-keyboard characters can be typed, so text with curly quotes, accents, or emoji is refused whole, and a paste is capped at 5000 characters. Long pastes take a while, since every character is a real keystroke; the agent stays paused until typing finishes. A newline presses Enter.
More than one agent session
Only one process can hold the Kiwi's serial port and capture device, so only one session uses the Kiwi at a time. Whichever session has the viewer port owns the Kiwi. Sessions that never touch the Kiwi don't claim it, so having the server configured everywhere costs nothing.
When a second session wants the Kiwi:
if the owner has been idle for 10 minutes (
KIWI_HANDOVER_IDLE_MS) and nobody has its viewer open, the Kiwi moves over without asking.otherwise the second agent is told the Kiwi is busy and asks you. If you agree, it calls
take_over, the first session lets go, and its tools say the Kiwi was taken until it callstake_overitself.an open viewer on the first session closes when it loses the Kiwi. Open the new link the agent gives you.
Only another Kiwi session can ask for a handover: the request is refused from a web page.
Running it yourself (serve)
If you'd rather keep one server running whatever the agents do, start it on its own:
KIWI_INVERT_SCROLL=1 node dist/index.js serve # or: npm run serveThat starts one long-running process on http://127.0.0.1:7523 with the viewer at / and a
streamable HTTP MCP endpoint at /mcp. Point the agent at it instead of launching its own:
claude mcp add --transport http kiwi http://127.0.0.1:7523/mcpA stdio session never takes the Kiwi from serve. It tells the agent to connect to /mcp or ask
you to stop that server. serve has to outlive the agent's command, so start it in a terminal you
own or as a login item.
Sharing control
You and the agent share the machine. When you click, scroll, or type in the viewer the agent is
paused ("Take over when I use it", on by default), and its input tools return an error telling it
to wait. Once you've sent no input for 15 seconds (KIWI_AUTO_RESUME_MS) the agent gets control
back on its own, and the status pill counts down to it. Any input you send, mouse moves included,
resets that countdown. Press "Resume agent" to hand control back sooner. Just moving the mouse over
the viewer does not pause it. A pause from the "Pause agent" button lasts until you press Resume.
The Activity panel (the icon at the top right) lists every agent action as it happens. It starts
hidden to give the screen more room, and the viewer remembers whether you left it open.
If the target's screen isn't 16:9 (most Macs are 16:10), the Kiwi sends its picture centred between black bars. The server finds those bars and maps clicks to the picture inside them, so the cursor lands where you or the agent pointed. Clicks on a bar go to the nearest edge of the screen.
The server only listens on localhost and rejects requests addressed to other hostnames, and only the viewer page itself can send input. Anything running on your Mac can still reach it, so don't expose the port to a network.
Tools
Tool | What it does |
| Capture the target screen as a JPEG (1280x720 by default). All coordinates refer to this image. |
| Click at (x, y); supports right/middle buttons, double and triple clicks, and held modifiers (e.g. |
| Move the pointer without clicking (hover). |
| Press, move smoothly, release. For selections, sliders, and drag-and-drop. |
| Wheel scroll up/down/left/right over a point. |
| Type text with US-layout keystrokes. |
| Press a key or shortcut: |
| Release every key and button (if something seems stuck). |
| Switch between normal HID and legacy boot-protocol HID (some BIOS screens need legacy). |
| Live viewer link, Kiwi model, firmware and bootloader versions, ports in use, and recent device log lines. |
| Open the live viewer in your browser, unless a viewer tab is already open. |
| Take the Kiwi from another agent session (stdio only, after you agree). |
Every input tool takes an optional screenshot: true. It returns a fresh capture once the UI has
settled, which saves the agent a round trip.
Configuration
All settings are optional environment variables.
Variable | Default | Meaning |
| auto | Serial device. Auto-detects the Kiwi's CH340 (USB |
|
| Serial baud rate. |
|
| Release the serial port after this much idle time. |
| auto | Capture device name (macOS/Windows) or |
|
| Capture mode requested from the Kiwi. |
|
| Width of screenshots sent to the agent (height keeps the aspect ratio). |
|
| Stop the background ffmpeg stream after this much idle time. |
|
| Frames per second of the background stream. |
|
| Viewer port (same as |
| off | Flip scroll direction, for targets with natural scrolling. |
|
| Delay between keyboard reports while typing. |
|
| Wait before the screenshot that follows an action. |
|
| After you take over in the viewer, give control back to the agent once you've sent no input for this long. |
|
| A session that hasn't used the Kiwi for this long, with no viewer open, hands it to another session without asking. |
| on | Find black bars around the target's picture and map the mouse inside them. Set to |
|
| ffmpeg binary. |
Manual testing CLI
The same code paths are available from the shell, which is handy for checking the hardware without an agent:
npm run cli -- info
npm run cli -- screenshot shot.jpg
npm run cli -- click 640 360
npm run cli -- scroll down 5 640 360
npm run cli -- key cmd+space
npm run cli -- type "hello world"
npm run cli -- hid-mode normalAfter npm run build it's also available as node dist/cli.js ....
Development
npm test # protocol unit tests, anchored on frames captured from real hardware
npm run typecheck
npm run dev # run the MCP server from source with tsxSource layout:
src/protocol.ts: frame encoding and decoding, CRC-8, HID report builders.src/link.ts: serial connection (auto-detect, warm-up, write serialization, idle close).src/video.ts: ffmpeg capture, with a warm MJPEG stream and a one-shot fallback.src/keys.ts: key names, chords, and the US-layout text map.src/kiwi.ts: high-level gestures (click, drag, scroll, typing).src/index.ts: the MCP server.src/cli.ts: the manual test CLI.
Troubleshooting
"Serial port ... is in use"
Quit the Cytrence Kiwi app.
"No Cytrence Kiwi serial port found"
The Kiwi's host-side USB-C cable isn't connected to this computer, or KIWI_SERIAL_PORT points somewhere else.
Screenshots fail on macOS
Grant Camera permission to the app that launches the server, then restart that app.
Scrolling goes the wrong way
Toggle KIWI_INVERT_SCROLL.
Keys do nothing in a BIOS or boot menu
Call set_hid_mode with legacy. Switch back to normal once the OS has loaded.
Wrong characters when typing
type_text assumes the target uses a US keyboard layout.
Disclaimer
This is an independent project, not affiliated with or endorsed by Cytrence. It relies on an undocumented protocol, so a firmware update could break it.
License
MIT
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
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Turns a phone into a camera+Bluetooth remote so AI assistants can see and control any PC.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceGives AI agents full keyboard, mouse, and screen access to a physical PC via a KVM server and OCR.6MIT
- AlicenseAqualityBmaintenanceEnables agents to remotely control IP-KVM devices such as GLKVM, PiKVM, and TinyPilot out-of-band using keyboard, mouse, HID, and power tools, with screenshot verification for each action.1224MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control remote desktops through screen capture, mouse movement, and keyboard input.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to see and control an existing Linux X11 desktop over SSH by taking screenshots and performing mouse, scroll, typing, and keyboard-shortcut actions across browsers, terminals, file managers, and other apps.MIT