cliptunnel-mcp

Operate locked-down remote machines through their clipboard — now with multi-remote support, autonomous agents, clipboard preservation, and agent heartbeat.

What it does

cliptunnel-mcp turns a shared clipboard into a reliable control channel between machines. When a remote machine sits behind a Citrix session, a locked-down VDI, or any environment that blocks SSH, file transfer, and networking but still exposes a clipboard, ClipTunnel tunnels commands through that single slot and exposes them as Model Context Protocol tools.

v0.7.0 ships the CT3 wire protocol v3 with prefixed endpoint IDs (C/R + 7 hex), announce-based discovery, multi-controller awareness, an agent heartbeat that keeps the remote roster self-healing, and clipboard preservation that restores the user's clipboard after every exchange.

The package ships four layers:

• Protocol — CT3 wire format with prefixed endpoint IDs (C/R + 7 hex), broadcast routing, keepalive pings, announce-based discovery, and typed messages (command, response, error, ack, ping, announce).
• Endpoints — Controller (operator side) with a remote + controller registry, and multiple Agent instances (remote side), each with a unique prefixed ID. Both run background threads with ARQ retransmission, sequence-bound deduplication, and generation-safe lifecycle.
• MCP server — a FastMCP application with 26 tools including shell, filesystem, binary transfer, sysinfo, remote agent management, connection listing, and announce-based discovery.
• Clipboard transport — backed by clipboard-event for cross-platform event-driven change detection, with user-clipboard preservation (non-protocol content is backed up and restored after each exchange).

Architecture

On startup the Controller broadcasts an ANNOUNCE. Each Agent generates a random prefixed ID (R + 7 hex), waits a random delay (0.1–4.0s), and sends back its sysinfo as a registration response. The Controller maintains a registry of all connected remotes and any other controllers it discovers. A keepalive thread pings remotes after 5 minutes of inactivity and marks them dead if no response is received within 30 seconds. Each Agent additionally runs a heartbeat thread that periodically re-sends its registration, so a lost announce response never leaves an agent invisible. After every exchange the Controller restores the user's clipboard content that was present before the protocol traffic.

Wire format

CT3|<from>|<to>|<seq>|<type>|<payload>

Registration and announce flow

Because the clipboard is a single last-writer-wins slot, simultaneous announce responses can collide and one agent's registration may be lost. The heartbeat below makes this self-healing: the missing agent re-registers on the next cycle.

Heartbeat

Each Agent runs a daemon thread that re-sends its registration (a RESPONSE with seq=0 carrying sysinfo) to every known controller on a configurable interval plus jitter. The jitter prevents multiple agents sharing a clipboard from synchronizing their writes. A lost heartbeat is harmless — the next one arrives. The controller's existing registration upsert path consumes it with no protocol or controller changes.

Keepalive

With the heartbeat active, the keepalive loop stays mostly idle — it only pings remotes that have stopped heartbeating, and is what ultimately marks a silent agent dead.

Clipboard preservation

The clipboard is the user's real pasteboard, so every protocol write would clobber whatever the user copied. ClipTunnel now preserves it:

• Backup — the transport observes every clipboard change. Any non-empty value that is not CT3 protocol traffic (CT3|…) is retained as the user-clipboard candidate. The backup is also seeded at construction from the initial value, so a startup announce never destroys pre-existing content.
• Guarded restore — after the Controller sends the final ACK of an exchange, it calls transport.restore_user_clipboard(). The restore happens only if the OS clipboard still holds this process's last self-write; if another process or the user wrote anything in between, the restore is a silent no-op (it would otherwise clobber that content). On success the backup is written back as a self-write.

This makes the heartbeat and the restore synergistic: a racy restore that clobbers an in-flight message is cured by the next heartbeat, and the user's clipboard survives the protocol traffic.

Installation

pip install cliptunnel-mcp          # core + cliptunnel-agent binary
pip install cliptunnel-mcp[server]  # adds MCP server binary (mcp>=1.2,<2)

Dependencies: clipboard-event>=0.2.0 (cross-platform clipboard change notifications).

Quick start

Agent (remote machine)

cliptunnel-agent

Antivirus / EDR workaround (Windows): unsigned .exe entry points may be quarantined. Use python -m instead:

python -m cliptunnel_mcp.agent    # instead of cliptunnel-agent
python -m cliptunnel_mcp.server   # instead of cliptunnel-mcp

The Agent generates a random prefixed ID, registers with the Controller by sending its sysinfo, then watches the clipboard for commands. It uses clipboard-event for change detection (event-driven on Windows and Wayland, polling on macOS and X11). A heartbeat thread re-registers every CLIPTUNNEL_HEARTBEAT_SECS (default 120s) so the Controller never loses it; set the variable to 0 or a negative value to disable it.

Controller + MCP server (operator machine)

Configure your MCP client (Claude Desktop, Cursor, Pi, etc.):

{
  "mcpServers": {
    "cliptunnel": {
      "command": "cliptunnel-mcp",
      "args": []
    }
  }
}

The server broadcasts an announce on startup, discovers connected remotes and any other controllers, and maintains a live registry with keepalive pings. After every exchange it restores the user's clipboard content.

Controller only (no MCP)

from cliptunnel_mcp.clipboard_transport import ClipboardTransport
from cliptunnel_mcp import Controller
import json

controller = Controller(transport=ClipboardTransport())

# Send to a specific remote
future = controller.send_command(json.dumps({"op": "shell", "cmd": "whoami"}), remote_id="R1b2c3d4")
result = future.result(timeout=30)

# List connected remotes
connections = controller.get_connections()
# {"remotes": {"R1b2c3d4": {"os": "Windows", "status": "alive", "last_seen": 1692634123.4, "last_seen_ago": 0.3, ...}}, "controllers": {...}}

Programmatic Agent

from cliptunnel_mcp.clipboard_transport import ClipboardTransport
from cliptunnel_mcp import Agent
from cliptunnel_mcp.operations import dispatch

agent = Agent(transport=ClipboardTransport(), handler=dispatch)
# Agent generates its own remote_id, registers automatically, and heartbeats every 120s.
# Disable the heartbeat with heartbeat_secs=0 (or CLIPTUNNEL_HEARTBEAT_SECS=0).

MCP tools

The server exposes 26 tools over stdio. All tools accept an optional remote_id parameter to target a specific remote. If omitted, the Controller picks the first alive remote.

Shell & filesystem

Binary transfer

System info

Remote agent (Copilot)

Connections & discovery

Operations

The dispatch handler supports these operations:

Remote agent

The Agent can run autonomous Copilot-powered agents on the remote machine. Each agent session:

• Uses the GitHub Copilot API with function calling (shell, fs_read, fs_write, fs_replace, fs_search, fs_list, fs_find)
• Runs asynchronously in a background thread
• Supports multi-turn conversations with remote_agent_continue
• Default model: mai-code-1.1-flash

Authentication

# Via MCP tools:
remote_agent_login()          # Returns user_code + verification_uri
# Open https://github.com/login/device, enter the code
remote_agent_login_status()   # Returns {status: "done", token_saved: true}

Token stored in .copilot_agent_token on the remote machine. The token lookup is relative to the agent process working directory, so launch the agent from a directory that contains (or can access) the token file.

API surface

Controller

The operator-side endpoint with remote + controller registry, keepalive, and clipboard restore.

Agent

The remote-side endpoint with auto-registration, heartbeat, and ping handling.

Constructor parameters: transport (required), handler (required), poll_interval, max_workers, response_ack_timeout, heartbeat_secs (default None → resolves CLIPTUNNEL_HEARTBEAT_SECS, then 120; <= 0 disables).

ClipboardTransport

Protocol primitives

Clipboard backend

ClipTunnel uses clipboard-event for cross-platform clipboard access and change detection:

The ClipboardTransport adapts clipboard-event to the Transport and RevisionMonitor protocols, backs up non-protocol clipboard content, and guards restores against concurrent writers. For custom setups, implement the Transport protocol directly.

Platform support

Development

# Create a virtual environment
uv venv && source .venv/bin/activate

# Install in development mode
uv pip install -e . pytest

# Run the test suite (275 tests)
python -m pytest -q
# or
python -m unittest discover -s tests -t .

# Bare mode — no install, just PYTHONPATH
PYTHONPATH=src:. python -m pytest -q

The test suite uses a deterministic ClipboardSlot test double. No clipboard hardware needed.

Lifecycle and coalescing semantics

• One command at a time: the Controller dispatches commands serially per target remote.
• Immediate ACK: the Agent ACKs every command before processing.
• One response at a time: the Agent holds one pending response; retransmits until the Controller's ACK.
• Announce discovery: the Controller broadcasts an ANNOUNCE on startup and on remote_discovery; agents and other controllers reply. Replies can collide on the shared slot; the heartbeat makes this self-healing.
• Heartbeat: each Agent re-sends its registration every CLIPTUNNEL_HEARTBEAT_SECS (default 120s) + jitter (0–15s); <= 0 disables. The controller upserts the roster on every heartbeat.
• Keepalive: Controller pings remotes after 5 min idle, marks dead if no response within 30s. With the heartbeat active, this only fires for agents that have stopped heartbeating.
• Clipboard preservation: the transport backs up non-CT3 clipboard content; the Controller restores it (guarded) after the final ACK of every exchange.
• Broadcast routing: to=* messages are processed by all remotes with random backoff; no ACK.
• Targeted routing: to=<R+7hex> messages are processed only by that remote; others ignore.
• Stale message guard: the Controller skips R/E with seq <= min_seq.
• Generation-safe: closing and restarting never strands threads.
• Paced writes: bounded inter-write gap prevents message loss.

Limitations

• Text-only clipboard: the protocol carries UTF-8 strings, and the preservation backup is text-only. Binary files are base64-encoded; rich content (images, RTF) copied by the user is not preserved by the restore.
• Shared slot: multiple remotes and controllers share one clipboard; the protocol serializes all traffic, and announce responses can race (mitigated by the heartbeat).
• No encryption: the wire format is plain base64.
• Multi-controller: multiple controllers are discovered and tracked, but they share the single clipboard channel — the protocol is designed for one primary Controller and multiple Agents.
• CT3-looking user content: if the user copies a string starting with CT3|, it is treated as protocol traffic and not backed up.

License

MIT — see LICENSE.