cliptunnel-mcp

Operate a locked-down remote machine through its clipboard.

What it does

cliptunnel-mcp turns a shared clipboard into a reliable control channel between two machines. When the 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.

The package ships three layers:

• Protocol — a wire format (CT1) with base64 payloads, sequence numbers, and typed messages (command, response, error, ack).
• Endpoints — Controller (operator side) and Agent (remote side), connected by an injected Transport. Both run background threads with ARQ retransmission, sequence-bound deduplication, and generation-safe lifecycle.
• MCP server — a FastMCP application that exposes the Controller's helpers as remote_shell, remote_fs_*, remote_upload, and remote_download tools over stdio.

The core package has zero dependencies. The MCP server requires the optional [server] extra (mcp>=1.2,<2).

Architecture

graph TD
  subgraph Operator["Operator machine"]
    Client["MCP client<br/>(Claude, Pi, Cursor, …)"]
    Server["MCP server<br/>(cliptunnel-mcp)"]
    Controller["Controller<br/>send_command → Future"]
    CT1["ClipboardTransport<br/>(OS clipboard)"]
  end

  subgraph Remote["Locked-down machine"]
    CT2["ClipboardTransport<br/>(OS clipboard)"]
    Agent["Agent<br/>ACK → process → R/E"]
    Dispatch["dispatch<br/>shell · fs · bin"]
  end

  Client -- "MCP / stdio" --> Server
  Server --> Controller
  Controller -- "CT1 wire" --> CT1
  CT1 -- "clipboard slot<br/>(last-writer-wins)" --> CT2
  CT2 --> Agent
  Agent --> Dispatch
  Dispatch -- "response" --> Agent
  Agent -- "CT1 wire" --> CT2
  CT2 -- "clipboard slot" --> CT1
  CT1 --> Controller

Both endpoints share a single last-writer-wins clipboard slot. The protocol uses stop-and-wait ARQ: the Controller writes one command, the Agent ACKs immediately, processes the command in a worker pool, then writes one typed response (R or E) and retransmits it until the Controller's matching ACK arrives. The Controller sends one command at a time and resolves futures as responses come back.

Wire format

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

Installation

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

Both modes install console entry points:

Quick start

Agent (remote machine)

The simplest way to run the Agent is the installed binary:

cliptunnel-agent

This builds a ClipboardTransport backed by the system clipboard (pbcopy/pbpaste on macOS, user32 on Windows, xclip/xsel on Linux) and wires operations.dispatch as the command handler. The Agent watches the clipboard slot, ACKs commands, processes them in a worker pool, and writes responses back. Press Ctrl+C to stop.

Controller + MCP server (operator machine)

On the operator side, configure your MCP client (Claude Desktop, Cursor, Pi, etc.) to launch the server binary:

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

The server binary injects a Controller backed by a ClipboardTransport and runs the FastMCP application over stdio. All remote_* tools are available immediately.

Note: the MCP server requires pip install cliptunnel-mcp[server].

Controller only (no MCP)

For programmatic use without an MCP client:

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

controller = Controller(transport=ClipboardTransport())

# Async — returns a Future
future = controller.send_command(json.dumps({"op": "shell", "cmd": "whoami"}))
result = future.result(timeout=30)

# Sync — blocks until response or timeout
output = controller.send_command_sync(json.dumps({"op": "fs.read", "path": "/etc/hostname"}))

Programmatic Agent

If you need a custom handler or transport:

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

agent = Agent(transport=ClipboardTransport(), handler=dispatch)
# Blocks until agent.close() — run in a thread or manage lifecycle yourself.

API surface

Controller

The operator-side endpoint. Sends commands asynchronously, dispatches one at a time, and resolves futures as responses arrive.

Constructor parameters: transport (required), timeout, retries, poll_interval, ack_timeout, initial_seq, persist_seq, seq_store.

Agent

The remote-side endpoint. Watches the slot, ACKs commands immediately, processes them in a worker pool, and writes one typed response at a time with retransmission.

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

dispatch

The default Agent handler. Parses JSON payloads and routes to the matching operation.

from cliptunnel_mcp.operations import dispatch

output, is_error = dispatch('{"op": "shell", "cmd": "echo hello"}')

Protocol primitives

Transport protocol

class Transport(Protocol):
    def read(self) -> str: ...
    def write(self, value: str) -> None: ...

class RevisionMonitor(Protocol):
    @property
    def revision(self) -> int: ...
    def wait_for_change(self, after: int, timeout: float = 1.0) -> int: ...

A transport must implement read/write (last-writer-wins). Implementing RevisionMonitor (or exposing wait_for_revision / wait_for_change) enables change-aware waits instead of polling.

Operations

The dispatch handler supports these operations:

MCP tools

The server exposes 13 tools over stdio:

Lifecycle and coalescing semantics

• One command at a time: the Controller dispatches commands serially. The pending command's seq is published atomically with the slot write so the reader never observes the command before the dispatcher.
• Immediate ACK: the Agent ACKs every command before processing, freeing the slot for the Controller.
• One response at a time: the Agent holds exactly one pending response envelope. A new command never implicitly ACKs a pending response — only the Controller's matching A(seq) releases it.
• Retransmission: both sides retransmit on ACK timeout. The Controller retries up to retries times (default 3). The Agent retransmits the response every response_ack_timeout seconds (default 1.0).
• Deduplication: the Agent's SeqTracker tracks per-seq state (new → processing → done). Duplicate commands are ACKed; done ones replay the cached typed response; in-flight ones are already being processed.
• Stale message guard: the Controller skips any R/E with seq <= min_seq — stale slot content from a previous session.
• Generation-safe: all stop state and queues are local to each instance. Closing and starting a new Agent or Controller never strands threads.
• Paced writes: the Controller enforces a bounded inter-write gap (2× poll interval) so the Agent can read each message before it is overwritten.

Backend selection

ClipTunnel ships ClipboardTransport, a transport backed by the OS clipboard (pbcopy/pbpaste on macOS, user32 on Windows, xclip/xsel on Linux). It implements both Transport and RevisionMonitor, so both endpoints get change-aware waits instead of pure polling. The binaries cliptunnel-agent and cliptunnel-mcp use it automatically.

For custom setups — a Citrix clipboard redirection, a shared Gist, a network pipe — implement the Transport protocol (read() -> str, write(str) -> None) and optionally RevisionMonitor (revision + wait_for_change). Inject it into Controller or Agent 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 (161 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 that models the last-writer-wins channel with revisions and bounded waits. No clipboard hardware is needed.

Limitations

• Text-only clipboard: the protocol carries UTF-8 strings. Binary files are base64-encoded, which roughly doubles their size over the wire.
• Single slot: the clipboard holds one value at a time. The ARQ protocol serializes all traffic through it, so throughput is bounded by the clipboard round-trip latency.
• No encryption: the wire format is plain base64. If the clipboard is observable, use an encryption layer in your transport or handler.

License

MIT — see LICENSE.