cliptunnel-mcp

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

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.5.0 introduces CT2 protocol v2 with multi-remote support, autonomous Copilot agents, and clipboard-event integration.

The package ships four layers:

• Protocol — CT2 wire format with 8-char hex remote IDs, broadcast routing, keepalive pings, and typed messages (command, response, error, ack, ping).
• Endpoints — Controller (operator side) with a remote registry, and multiple Agent instances (remote side), each with a unique hex ID. Both run background threads with ARQ retransmission, sequence-bound deduplication, and generation-safe lifecycle.
• MCP server — a FastMCP application with 25 tools including shell, filesystem, binary transfer, sysinfo, remote agent management, and connection discovery.
• Clipboard transport — backed by clipboard-event for cross-platform event-driven change detection.

Architecture

The Controller broadcasts a register command on startup. Each Agent generates a random 8-hex ID, waits a random delay (0.1–4.0s), and sends back its sysinfo. The Controller maintains a registry of all connected remotes. A keepalive thread pings remotes after 5 minutes of inactivity and marks them dead if no response is received within 30 seconds.

Wire format

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

Registration flow

Keepalive

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 8-hex 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).

Controller + MCP server (operator machine)

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

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

The server broadcasts a register command on startup, discovers connected remotes, and maintains a live registry with keepalive pings.

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="a1b2c3d4")
result = future.result(timeout=30)

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

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 and registers automatically

MCP tools

The server exposes 25 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

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.

API surface

Controller

The operator-side endpoint with remote registry and keepalive.

Agent

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

Constructor parameters: transport (required), handler (required), poll_interval, max_workers, response_ack_timeout.

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. 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 (232 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.
• Keepalive: Controller pings remotes after 5 min idle, marks dead if no response within 30s.
• Broadcast routing: to=* messages are processed by all remotes with random backoff; no ACK.
• Targeted routing: to=<hex> 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. Binary files are base64-encoded.
• Shared slot: multiple remotes share one clipboard; the protocol serializes all traffic.
• No encryption: the wire format is plain base64.
• One Controller: the protocol supports one Controller and multiple Agents, not multiple Controllers.

License

MIT — see LICENSE.