cliptunnel-mcp

Operate locked-down remote machines through their clipboard, an HTTPS repeater, or Firebase — with multi-remote support, autonomous agents, clipboard preservation, agent heartbeat, and optional AES-256-GCM encryption.

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.

v1.0.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, clipboard preservation that restores the user's clipboard after every exchange, four transport options — clipboard (default), HTTPS repeater, Firebase Realtime Database, and WebSocket repeater — optional AES-256-GCM encryption that works with any transport, sanitized transport endpoint reporting in sysinfo, PowerShell shell execution on Windows, error responses that surface the agent's actual error output, and zombie job detection for commands whose clipboard response was lost.

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 27 tools including shell, filesystem, binary transfer, sysinfo, remote agent management, connection listing, announce-based discovery, and remote install instructions.
• Transport layer — clipboard (default, backed by clipboard-event with user-clipboard preservation), HTTPS repeater (optional, with bearer auth), Firebase Realtime Database (optional, hosted slot with server timestamps), or WebSocket repeater (optional, local or remote relay). All implement the same Transport and RevisionMonitor protocols — the Controller and Agent are fully transport-agnostic. An optional EncryptedTransport decorator adds AES-256-GCM encryption on top of any transport.

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 (clipboard transport only — the HTTPS transport does not touch the user's clipboard).

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 channel 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. The clipboard transport 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. The Agent also restores the user's clipboard after each registration heartbeat, since registrations are fire-and-forget — no controller writes back to clean the slot.

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), cryptography>=42 (AES-256-GCM encryption), plus tomli on Python 3.10 only (TOML config file parsing; stdlib from 3.11).

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 (or connects to the repeater / Firebase RTDB if CLIPTUNNEL_TRANSPORT is https or firebase) for commands. It uses clipboard-event for clipboard 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. When using the clipboard transport, it restores the user's clipboard content after every exchange.

Controller only (no MCP)

from cliptunnel_mcp.transport_factory import build_transport
from cliptunnel_mcp import Controller
import json

controller = Controller(transport=build_transport())

# 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.transport_factory import build_transport
from cliptunnel_mcp import Agent
from cliptunnel_mcp.operations import dispatch

agent = Agent(transport=build_transport(), 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).
# Set CLIPTUNNEL_TRANSPORT=https (repeater) or =firebase (Firebase RTDB)
# to use a network transport instead of the clipboard.
# Set CLIPTUNNEL_AES_KEY to enable AES-256-GCM encryption on any transport.

MCP tools

The server exposes 27 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 resolution order: the [copilot].oauth_token key in the config file (see Configuration) takes precedence; the legacy .copilot_agent_token file on the remote machine is still supported as a fallback. The token lookup for the legacy file 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

HttpsTransport

Constructor parameters: repeater_url (required), bearer_token (required), http_client (optional, injectable for tests), sse_reconnect_delay, poll_timeout, request_timeout.

FirebaseTransport

Constructor parameters: database_url (required), auth_token (required), node_path (default "cliptunnel"), http_client (optional, injectable for tests), sse_reconnect_delay, request_timeout.

EncryptedTransport

A decorator that wraps any transport with AES-256-GCM encryption. When CLIPTUNNEL_AES_KEY is set, build_transport() automatically wraps the selected transport.

Constructor parameters: inner (required, any Transport), aes_key (required, 32 bytes).

build_transport() factory

crypto module

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 (513 tests with both pytest and unittest)
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 clipboard 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 wire encryption by default: the CT3 wire format is plain base64. Set CLIPTUNNEL_AES_KEY to enable AES-256-GCM encryption on any transport (clipboard, HTTPS, or Firebase).
• Multi-controller: multiple controllers are discovered and tracked. With the clipboard transport they share one channel; with the HTTPS transport they share one repeater slot. 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.

Configuration

Configuration has two layers with strict precedence:

1. Environment variables (highest precedence)
2. Config file (TOML, default ~/.cliptunnel/config.toml)
3. Built-in defaults (lowest)

The config file path resolves as: --config PATH CLI flag (on both cliptunnel-agent and cliptunnel-mcp) > CLIPTUNNEL_CONFIG env var > ~/.cliptunnel/config.toml. A missing config file is not an error — all settings simply fall through to the environment/default layers.

Ready-to-edit examples: config.toml-example-controller (operator machine) and config.toml-example-agent (remote machine). Copy one to ~/.cliptunnel/config.toml, edit the values, chmod 600, and no environment variables are needed.

Full annotated example covering every supported section:

# ~/.cliptunnel/config.toml

[transport]
type = "clipboard"                  # "clipboard" (default), "https", or "firebase"
repeater_url = "https://repeater.example.com"   # required when type = "https"
repeater_token = "agent-bearer-token"           # required when type = "https"
firebase_url = "https://NAME-default-rtdb.firebaseio.com"  # required when type = "firebase"
firebase_token = "firebase-auth-token"                     # required when type = "firebase"

[encryption]
aes_key = "QUJDREVGR0hJSktMTU5PUFFSU1RVVldYWVphYmNkZWY="  # base64 of 32 bytes; enables AES-256-GCM on any transport

[heartbeat]
interval_secs = 120                 # <= 0 disables the heartbeat

[copilot]
oauth_token = "gho_xxxxxxxxxxxxxxxxxxxx"  # GitHub Copilot OAuth token; takes precedence over the legacy .copilot_agent_token file

Security: this file holds secrets. Create it user-only-readable (mkdir -p ~/.cliptunnel && chmod 700 ~/.cliptunnel && chmod 600 ~/.cliptunnel/config.toml). The loader logs a warning (never fatal) if the file is readable by group or others.

The legacy .copilot_agent_token file remains fully supported as a fallback: [copilot].oauth_token in the config file wins when both exist.

Transport selection (Controller and Agent)

Encryption (Controller and Agent)

Heartbeat (Agent)

Repeater service (repeater only)

Copilot agent (Agent only)

HTTPS repeater transport

When the clipboard channel is unavailable (no shared clipboard across networks), monitored by DLP agents, or you need NAT traversal, ClipTunnel can use an HTTPS repeater as an alternative transport. Both the Controller and Agent are outbound HTTPS clients of a small relay service — no inbound ports needed on the remote machine.

Architecture

Controller  <--HTTPS/SSE-->  Repeater  <--HTTPS/SSE-->  Agent
(operator)                    (relay)                   (remote VDI)

The repeater is a zero-knowledge relay: it authenticates peers via bearer tokens but cannot decrypt content. When AES is enabled, the repeater never sees plaintext even if TLS is terminated at its edge.

When to use it

• The remote machine has outbound HTTPS but no inbound reachability (NAT, firewall).
• The clipboard channel is monitored, filtered, or unreliable (DLP).
• You want traffic that blends with normal web API usage rather than clipboard data movement.

Setup

1. Deploy a repeater. Run the repeater service (see below) at a URL the Agent can reach. Deploy behind a TLS proxy (Caddy, Cloudflare, API Gateway).

2. Configure the Controller. Set the transport to https on the operator machine — either via env vars (CLIPTUNNEL_TRANSPORT=https plus repeater URL and bearer token) or via a config file ([transport] type = "https").

3. Get install instructions. Call the remote_install_instructions MCP tool from your MCP client. It returns exact env vars and commands for the remote side.

4. Start the Agent. On the remote VDI, run cliptunnel-agent with the environment variables from the install instructions. The Agent connects outbound to the repeater via HTTPS.

Environment variables

AES-256-GCM encryption

When CLIPTUNNEL_AES_KEY is set, build_transport() wraps the selected transport in EncryptedTransport, which encrypts the full CT3 wire string with AES-256-GCM before writing it to the transport, and decrypts it after reading. The format is base64(nonce[12] ‖ ciphertext+tag[16]). The repeater, the Firebase database, and the clipboard never see plaintext.

This works with any transport — clipboard, HTTPS, or Firebase. The encryption layer is a decorator that sits between the Controller/Agent and the underlying transport.

Generate a key:

python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"
# or, equivalently:
openssl rand -base64 32

Set it on both the Controller and the Agent (out-of-band, not over the channel):

export CLIPTUNNEL_AES_KEY=<the base64 string from above>

If CLIPTUNNEL_AES_KEY is not set, the transport passes plaintext (base64 CT3). Encryption is optional and backward-compatible.

Repeater service

The repeater is a small stdlib-only HTTP service (no third-party deps). For production deployment with automatic HTTPS, see deploy/ for Docker + Caddy and Cloudflare Tunnel guides.

# The repeater is stdlib-only (no additional deps), included in the core package.
python -m cliptunnel_mcp.repeater

Repeater environment variables:

The repeater has three endpoints, all requiring Authorization: Bearer <token>:

The repeater state is ephemeral (in-memory). On restart, peers self-heal via the heartbeat mechanism. No database, no disk.

Install instructions tool

The remote_install_instructions MCP tool returns installation instructions for the remote agent based on the Controller's active transport:

• Clipboard: returns pip install cliptunnel-mcp and cliptunnel-agent (no env vars needed).
• HTTPS: returns pip install cliptunnel-mcp, the repeater URL, bearer token, AES key (if set), and the full cliptunnel-agent command with env-var prefixes.

Security: the tool output contains sensitive config (tokens, AES key). Do not log it or share it insecurely. The tool returns instructions for the operator, not a script that auto-executes.

Install extras

pip install cliptunnel-mcp          # core + clipboard transport + AES encryption (cryptography included)
pip install cliptunnel-mcp[server]  # + MCP server (mcp>=1.2,<2)

Firebase transport

When you have no machine to host the HTTPS repeater on, ClipTunnel can use a Firebase Realtime Database as the shared slot instead — free tier, no server to deploy, outbound HTTPS only on both sides.

The slot is one JSON node (default path /cliptunnel) shaped {"v": "<wire string>", "r": <server timestamp ms>}. Writes are REST PUTs with {".sv": "timestamp"} so Firebase stamps r from its server clock — a monotonic revision shared by all writers. Updates stream back over Server-Sent Events, with snapshot resync on reconnect, exactly like the HTTPS transport.

Prefer it over the self-hosted repeater when you want zero infrastructure and can tolerate Google as the host; prefer the repeater when you want the relay to be a zero-knowledge service you control. Note that the database admin can see node contents — AES encryption (CLIPTUNNEL_AES_KEY) composes identically here and is strongly recommended, since without it the RTDB stores the CT3 wire string in plaintext.

Configure both sides:

[transport]
type = "firebase"
firebase_url = "https://NAME-default-rtdb.firebaseio.com"   # https only
firebase_token = "database-or-oauth-token"

Or via env vars: CLIPTUNNEL_TRANSPORT=firebase with CLIPTUNNEL_FIREBASE_URL and CLIPTUNNEL_FIREBASE_TOKEN. Auth failures (HTTP 401/403) raise TransportAuthError; both peers self-heal via the heartbeat.

License

MIT — see LICENSE.