mcp-clipstream 0.3.2

MCP server + persistent TUI for clean clipboard capture from Claude Code sessions

mcp-clipstream

Clean clipboard capture for Claude Code. An MCP server that pushes copyable text into a persistent, scrollable TUI buffer — before the terminal renderer mangles it with ANSI codes, box-drawing characters, indentation padding, or hard line breaks.

Status: v0.3.1 (alpha) — clip, clip_table, clip_code, clip_cmd tools; syntax-highlighted previews; per-kind row colours; live search (f), session filter (s), expand view (e); at-copy-time format picker for tables. macOS-tested. See the roadmap for what's next.

Why

Copying text from Claude Code's terminal output is broken in ways that have been documented for nearly a year (issues #4686, #5097, #15199, #18170, #26016, #35446): extra spaces in code blocks, vertical bars from TUI renderer, hard line breaks at 80 characters, leading indentation baked in as real characters. Existing workarounds clean up after the damage. This captures the text before the terminal ever touches it.

How it works

 Claude Code ──tool call──▶ MCP server ──UDS──▶ clipstream TUI ──pbcopy──▶ clipboard
                            (mcp-clipstream)    (clipstream)

1. mcp-clipstream is a small MCP server spawned by Claude Code.
2. It exposes four tools: clip (catch-all text), clip_code (code blocks with a language hint), clip_cmd (shell commands with a shell hint), and clip_table (structured tables). Claude Code picks the right one for whatever it's producing.
3. The tool writes the clean text as a JSON message to a Unix domain socket at /tmp/clipstream.sock.
4. clipstream is a Textual TUI you run in a dedicated terminal tab. It listens on the socket, buffers every clip from every Claude Code session, and lets you scroll, select, and copy.

No ANSI codes. No hard wraps. No "please pipe through pbcopy" prompts.

Install

uv tool install mcp-clipstream
# or: pipx install mcp-clipstream

This gives you two entry points:

• clipstream — the TUI (you run this).
• mcp-clipstream — the MCP server (Claude Code runs this).

Upgrade later with uv tool upgrade mcp-clipstream.

Setup

1. Register the MCP server with Claude Code. One command:

claude mcp add clipstream --scope user $(which mcp-clipstream)

Verify with claude mcp list.

2. Auto-approve the clipstream tools so Claude Code stops prompting on every call. Merge this into ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__clipstream__clip", "mcp__clipstream__clip_table"]
  }
}

Restart any running Claude Code sessions after either step.

3. Tell Claude Code when to use it. Add to ~/.claude/CLAUDE.md (applies to every project) or a project-level CLAUDE.md:

## Clipstream clipboard

Push copyable output through the clipstream MCP server so the user gets clean text without terminal-renderer artifacts. Pick the right tool by content kind:

- **Shell commands** → `clip_cmd(command, shell="bash", label="…")`. One per command (or one for a multi-line script).
- **Code blocks** → `clip_code(code, language, filename=None, label="…")`. Always pass `language` (e.g. `"python"`, `"typescript"`, `"sql"`). Pass `filename` when the user is creating or editing a specific file.
- **Tables** → `clip_table(headers, rows, label="…")`. Lists of column names and lists of cell strings. The user picks Markdown / TSV / HTML rich at copy time.
- **Everything else** (configs, URIs, tokens, file paths, structured prose) → `clip(content, label="…", lang="…" if applicable)`.

Always include a short `label` so entries are scannable in the TUI.

Do not clip:
- Conversational text or explanations.
- Single-word answers, yes/no, very short inline values.
- Content the user just asked about but isn't grabbing.

4. Run the TUI in a spare terminal tab:

clipstream

Using it

• ↑ / ↓ — navigate clips
• Enter — copy selected clip to system clipboard
• f — find (live multi-token search across content, label, filename, kind, language, shell, session)
• s — cycle session filter (all → first session → second session → …)
• e — expand selected clip in a full-screen view (line numbers + syntax highlighting; Enter copies, Esc closes)
• d — delete selected clip
• c — clear all
• q — quit
• Esc — clear search / dismiss expand view

The status bar shows sessions: N | clips: visible/total | filter: … | find: … so you always know what's filtered.

New clips appear at the top with their source session label and a short preview. Each row is colour-coded by kind:

• green header — clip_code (Python, TypeScript, SQL, etc. — preview is syntax-highlighted)
• yellow header — clip_cmd (shell command, preview highlighted)
• cyan header — clip_table (preview shows markdown form)
• neutral — plain clip

Tables: when you press Enter on a clip_table row, a format picker appears:

• m — Markdown (GitHub, docs, chat)
• t — TSV (paste into Excel / Google Sheets / Numbers — each cell lands in its own column)
• h — HTML rich (paste into Gmail / Notion / Word / Apple Mail — renders as a real table, not raw markup)
• Esc — cancel

Configuration

Environment variables (TOML config file lands in v0.3.0):

Variable	Default	Purpose
CLIPSTREAM_SOCKET	/tmp/clipstream.sock	Unix domain socket path
CLIPSTREAM_SPOOL	~/.clipstream/spool.jsonl	Local fallback when TUI is down
CLIPSTREAM_SESSION	CWD basename	Override session label

CLI flags on clipstream:

clipstream --socket /tmp/clipstream.sock --max-clips 500

Roadmap

• v0.1.0 — MVP: clip tool, UDS transport, list view, pbcopy, macOS only.
• v0.2.x — clip_table with at-copy-time format picker (Markdown / TSV / HTML rich for Gmail/Notion/Word).
• v0.3.0 — clip_code and clip_cmd tools, syntax-highlighted previews (monokai), per-kind row colours.
• v0.3.1 (current) — Live search (f), session filter (s), expand view (e for full-screen detail with line numbers).
• v0.3.2 — ~/.clipstream/config.toml, themes (default + minimal), --persist flag for JSONL history.
• v0.3.3 — Linux clipboard validation (xclip / wl-copy), docs polish.
• v0.4.0 — pinning, chaining, auto-copy mode, Claude Code post-response hook.

Development

git clone https://github.com/shamis6ali/mcp-clipstream
cd mcp-clipstream
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy src

License

MIT © Orchestrator AI Systems Ltd.