mcp-rustdesk

Let an LLM see and control a remote machine over the RustDesk protocol.

This MCP server exposes the live RustDesk peer connection (E2EE NaCl

• AV1/H264/VP9 codecs + NAT traversal via your own hbbs) as a set of tools any MCP-compatible client (Claude Code, Claude Desktop, Cursor, …) can drive: connect, screenshot, click, scroll, type, key, plus an optional Gemini Live "watcher" that streams the frames to Gemini in parallel for continuous narration.

First public MCP that wraps RustDesk. Inspired by the existing VNC and computer-use MCPs, but with the security and codec advantages of RustDesk's protocol.

Runs on Linux, macOS and Windows (daemon + MCP server). The daemon ships a cross-platform loopback IPC (TCP 127.0.0.1 + token auth) so the same code path works on every host.

Why RustDesk and not VNC?

The MCP layer always returns one PNG per screenshot call — no multimodal LLM API today (April 2026) ingests a real video stream as input. The Gemini Live watcher (optional) bridges that gap by feeding frames continuously to Gemini and exposing its textual observations back through MCP.

Architecture

LLM client (Claude Code, etc.)
    │ stdio MCP
    ▼
mcp-server/server.py            ← Python, FastMCP
    │ TCP 127.0.0.1 + token JSON-RPC
    ▼
rustdesk-headless               ← Rust, built from RustDesk + our patch
    │ RustDesk protocol (E2EE)
    ▼
remote peer (any RustDesk client, any OS)

At startup the daemon binds 127.0.0.1:0 (OS picks a free port), generates a 32-byte random auth token, and writes a user-only rendezvous file ({host, port, token, pid}) the Python server reads to locate and authenticate to it. No Unix sockets, no named pipes — one code path on every OS.

A local HTTP viewer (rustdesk_viewer_start) lets a human watch the exact frames the LLM sees, in real time.

Repository layout

.
├── headless/                    Rust source for the headless RustDesk binary
│   ├── headless.rs              gets copied into rustdesk/src/bin/
│   ├── lib.rs.patch             visibility patch on the rustdesk crate
│   ├── apply.sh                 Linux / macOS: clone, patch, build
│   └── apply.ps1                Windows:       clone, patch, build
└── mcp-server/                  Python MCP server
    ├── server.py
    ├── requirements.txt
    └── pyproject.toml

Install

Option A — pre-built release (quickest)

Download the archive for your OS from the latest release:

• rustdesk-headless-linux-x64.tar.gz
• rustdesk-headless-macos-arm64.tar.gz / -macos-x64.tar.gz
• rustdesk-headless-windows-x64.zip

Extract the binary anywhere on your $PATH (or note its absolute path).

Option B — build from source

First build pulls ~700 crates plus libvpx/libyuv/opus/aom via vcpkg — count 30–60 min.

Linux / macOS:

git clone https://github.com/meumeu-dev/mcp-rustdesk.git
cd mcp-rustdesk
./headless/apply.sh                    # clones rustdesk + patches + cargo build

Outputs rustdesk/target/release/rustdesk-headless.

Windows (PowerShell):

git clone https://github.com/meumeu-dev/mcp-rustdesk.git
cd mcp-rustdesk
.\headless\apply.ps1

Outputs rustdesk\target\release\rustdesk-headless.exe. Requires Visual Studio 2022 Build Tools, Rust (rustup default stable-msvc), and choco install cmake nasm yasm.

Set up the Python MCP server

python3 -m venv mcp-server/.venv
mcp-server/.venv/bin/pip install -r mcp-server/requirements.txt

On Windows:

python -m venv mcp-server\.venv
mcp-server\.venv\Scripts\pip install -r mcp-server\requirements.txt

Register the MCP with your client

Claude Code (Linux / macOS):

claude mcp add rustdesk -s user \
  -e GEMINI_API_KEY="..." \
  -e RUSTDESK_VIEWER_PORT=8765 \
  -- "$PWD/mcp-server/.venv/bin/python" "$PWD/mcp-server/server.py"

Or as plain JSON in your client's MCP config:

{
  "mcpServers": {
    "rustdesk": {
      "command": "/abs/path/to/mcp-server/.venv/bin/python",
      "args": ["/abs/path/to/mcp-server/server.py"],
      "env": {
        "GEMINI_API_KEY": "AIza...",
        "RUSTDESK_VIEWER_PORT": "8765"
      }
    }
  }
}

Start the daemon

./rustdesk/target/release/rustdesk-headless &

Windows:

Start-Process -FilePath .\rustdesk\target\release\rustdesk-headless.exe

The daemon binds 127.0.0.1:<random port> and writes a rendezvous file containing the port and auth token. The Python MCP server reads it to connect — no manual port / token plumbing needed.

Rendezvous file location (auto-detected by both daemon and client):

Run the daemon as the same user that runs the MCP server (file permissions are user-only).

If you self-host RustDesk (recommended), make sure ~/.config/RustDesk-headless/RustDesk-headless2.toml has your custom-rendezvous-server and key, OR pass them per-call to rustdesk_connect. Alternatively, copy your existing ~/.config/rustdesk/ to ~/.config/RustDesk-headless/ once at setup.

Environment variables

Consumed by the Python server:

Consumed by the daemon:

MCP tools

Security

• Daemon binds 127.0.0.1:<random> only; the first frame on every connection must be an auth call with the shared token from the rendezvous file. Mismatched / missing tokens are rejected before any RPC is processed. The token comparison is constant-time.
• Rendezvous file is written user-only (0600 on Unix; on Windows it lives under %LOCALAPPDATA% which is user-ACL'd by default).
• The HTTP viewer binds to 127.0.0.1 only — tunnel via SSH if you want remote access.
• Passwords pass through the loopback connection, then the RustDesk protocol's E2EE — they are never logged.
• The daemon never executes shell commands on either end.
• Screenshots go in MCP responses; if your LLM provider logs prompts, every frame the LLM sees is logged with them. Treat the remote peer accordingly.
• The daemon refuses to start with RUSTDESK_APPNAME=RustDesk so it can never collide with an installed classic RustDesk client's config dir, named pipe, or IPC socket.

Status

MVP. Tested on Linux x86_64 hosts driving Linux and Windows peers through a self-hosted hbbs/hbbr. macOS and Windows host builds are produced by CI (see .github/workflows/build.yml); tested via CI, community testing welcome. Patches against RustDesk 1.4.x.

Caveats

• Peer-side input permissions must be granted on the remote RustDesk client (Authorizations panel: keyboard, mouse, clipboard). Without them the daemon connects, frames stream, but _click / _type / _key calls are silently dropped by the peer. A missing permission looks identical to a wrong key mapping — verify by clicking the corresponding toggle in the remote RustDesk UI.
• Multi-display peers: only display 0 is exposed for now.
• The Gemini Live watcher's video sessions cap at ~2 minutes; the watcher reconnects transparently but you may see brief gaps in observations.
• macOS: first run will ask for Accessibility and Screen Recording permissions (System Settings → Privacy & Security). These are granted per-binary path, separate from any RustDesk.app grant.
• Windows: SmartScreen may block the first run of an unsigned binary — "More info" → "Run anyway". If your organization runs AppLocker, whitelist the binary path.
• The daemon stores its identity under a separate config dir (RustDesk-headless/) so it never interferes with a classic RustDesk install. The trade-off: you need to copy or re-enter your custom rendezvous server and key once.

License

MIT for our patches and the Python server. The compiled rustdesk-headless binary, being a derivative work of RustDesk, is distributed under AGPL-3.0. See LICENSE.