<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.

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

## Install

Prerequisites: [CopyQ](https://hluk.github.io/CopyQ/), Python 3.12 or newer, and
[uv](https://docs.astral.sh/uv/). CopyQ must be running.

```powershell
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:

```powershell
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:

```powershell
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:

```powershell
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

```powershell
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](https://github.com/AutoraLabs/copyq-mcp/blob/main/docs/architecture.md)
for the implementation boundary and
[contributing](https://github.com/AutoraLabs/copyq-mcp/blob/main/CONTRIBUTING.md)
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](https://github.com/AutoraLabs/copyq-mcp/blob/main/LICENSE);
AutoraLabs names and marks are not granted under that software license.