MCP CopyQ Server

You can bridge CopyQ, a powerful clipboard manager, with MCP-enabled agents to read, write, and organize clipboard items through a lightweight MCP server. This guide shows you how to install, configure, and use the CopyQ MCP server so you can automate workflows and keep data in sync across tools.

How to use

Launch the MCP CopyQ server and connect your MCP client to it. You will be able to read from CopyQ tabs, add or update items, move items between tabs, and validate calls before executing actions. Use predefined commands to perform common tasks such as listing items, reading a specific item, or updating text and tags.

Key capabilities you will use frequently include: reading data from CopyQ in tree/list/item modes, adding new items to a tab, updating an item field (text, tags, or notes) with various edit modes, and creating or deleting sub-tabs under the workspace section.

How to install

Prerequisites you need before installation are Python 3.11 or newer and CopyQ installed and running. Ensure you know the CopyQ executable path if you need to interact with CopyQ from your system.

# Prerequisites
python --version  # should be 3.11+
copyq --version     # ensure CopyQ is installed and accessible

# Install the MCP CopyQ server
# Clone or navigate to your project directory
# Example path used here is illustrative; adapt to your environment
cd C:\sts\projects\mcp-copyq

# Create a virtual environment using the helper tool
uv venv

# Install the MCP server in editable mode
uv pip install -e .

# Start the MCP CopyQ server
uv run mcp-copyq

Configuration and usage notes

Configure the MCP client to connect to the local server started by the previous steps. You can use a small configuration snippet to register the server as a local stdio MCP endpoint.

{
  "mcpServers": {
    "copyq": {
      "command": "uv",
      "args": ["run", "mcp-copyq"]
    }
  }
}

Starting in Claude Desktop (example)

If you use Claude Desktop to drive MCP interactions, register the CopyQ server as a stdio MCP server with the following configuration.

{
  "mcpServers": {
    "copyq": {
      "command": "uv",
      "args": ["run", "mcp-copyq"]
    }
  }
}

Available tools

mcp_read

Universal read tool to fetch data from CopyQ storage in various modes (tree, list, item, search) with options for depth, pagination, and selective fields.

mcp_write

Universal write tool to add, update, delete, move items and manage tabs in CopyQ MCP storage, with fine-grained edit modes and preview capability.

mcp_validate

Validation tool to check parameters before executing read/write operations and catch issues early.