<p> <a href="https://autoralabs.com"> <img src="https://raw.githubusercontent.com/AutoraLabs/copyq-mcp/main/docs/assets/autoralabs-logo.svg" alt="AutoraLabs" width="240"> </a> </p>

CopyQ MCP

Give AI agents direct access to your CopyQ text history, and keep dictation transcripts out of your normal clipboard tab.

CopyQ remains the database and clipboard UI. This package adds one local MCP server and an optional Windows setup command. It does not run a daemon, expose a network port, or create a second clipboard store.

MCP client ── stdio ──► CopyQ MCP ──► CopyQ history
                                         ├─ &clipboard
                                         ├─ Codex Dictation
                                         └─ Flow

Install

Prerequisites: CopyQ, Python 3.12 or newer, and uv. CopyQ must be running.

uv tool install https://github.com/AutoraLabs/copyq-mcp/releases/download/v0.1.0/copyq_mcp-0.1.0-py3-none-any.whl
copyq-mcp doctor
codex mcp add copyq -- copyq-mcp

Restart Codex after adding the server. Other stdio MCP clients can use copyq-mcp as the server command.

Use from an agent

Ask naturally:

• “Use the three things I just copied.”
• “Read the fifth item in my clipboard history.”
• “Search my clipboard for the nginx configuration.”
• “Check the Codex Dictation tab for my last transcript.”

The MCP server exposes three tools:

• clipboard_read(start=0, count=5, tab="clipboard") reads a page of text history, newest first. The result includes next_start for later pages.
• clipboard_search(query, start=0, count=20, tab="clipboard", case_sensitive=false) searches from any row and returns a continuation.
• clipboard_tabs() lists every CopyQ tab and its item count.

clipboard is an alias for CopyQ's &clipboard tab. Exact tab names also work. Text items include their zero-based CopyQ row, copy timestamp, origin, and source window when those fields exist.

Keep dictation out of normal history

On Windows, CopyQ MCP can route matched Codex global dictation and Wispr Flow transcripts into dedicated tabs:

copyq-mcp setup --dictation auto --modern

auto enables compatible providers found on the machine. Use codex, wispr, both, or none to choose explicitly. Classification fails open: if a provider changes or cannot be inspected, the clipboard item stays in &clipboard.

--modern applies a small, opinionated configuration:

• retain 50,000 items;
• show tab item counts and one-based row labels;
• show six text lines per item with a 100-pixel maximum height;
• display copy time;
• use Win+V to show or hide CopyQ.

Preview changes without writing anything:

copyq-mcp setup --dictation auto --modern --dry-run

The first setup preserves a pre-setup JSON backup for that CopyQ session; repeated setup keeps the baseline instead of backing up an already-configured state. Restore it with:

copyq-mcp restore

Restore leaves provider tabs and their contents intact.

Configuration

The server discovers CopyQ on PATH and in common install locations. Two environment variables cover non-default installations:

Variable	Meaning
COPYQ_MCP_EXECUTABLE	Exact path to the CopyQ executable
COPYQ_MCP_SESSION	Existing CopyQ session name

copyq-mcp doctor reports CopyQ readiness, tab counts, routing state, and provider compatibility.

Deliberate limits

• Version 0.1 reads text history only. It does not write, delete, paste, pin, or reorder clipboard items.
• Read and search pages contain at most 100 text items. Pagination can continue through the complete tab.
• Very large individual text items are returned as an explicit truncated prefix.
• Dictation routing is Windows-only. Codex and Wispr are external applications; an upstream storage or clipboard-behavior change can require a classifier update. Routing fails open so that such a change causes clutter, not data loss.
• Wispr matching uses exact recent transcript text. Manually copying the same text within ten minutes can also send that copy to Flow.

Development

git clone https://github.com/AutoraLabs/copyq-mcp.git
cd copyq-mcp
uv sync --locked --all-groups
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest --cov --cov-report=term-missing
uv build

See architecture for the implementation boundary and contributing for the small set of project rules.

CopyQ MCP is an independent AutoraLabs integration. It is not affiliated with or endorsed by CopyQ, OpenAI, or Wispr Flow. Source is licensed under the MIT License; AutoraLabs names and marks are not granted under that software license.