MCP 服务器

clipboard-mcp

A simple MCP server that allows AI assistants to read from and write to the system clipboard.

README

Clipboard MCP Server

A Model Context Protocol (MCP) server that provides system clipboard read and write capabilities for AI assistants like Claude.

⚠️ Important: Install System Dependencies First

Linux users must install clipboard utilities before using this package:

# For X11 (most common)
sudo apt install xclip xsel

# For Wayland
sudo apt install wl-clipboard

# Other distributions
sudo dnf install xclip xsel      # Fedora/RHEL
sudo pacman -S xclip xsel         # Arch Linux

WSL users: Usually works out of the box using Windows clipboard tools. If you encounter issues, install xclip xsel as above.

macOS and Windows users: No additional dependencies needed!

Features

read_clipboard: Read text content from the system clipboard
write_clipboard: Write text content to the system clipboard
Cross-platform support (Linux, macOS, Windows, WSL)
Lightweight with minimal dependencies

Installation

Option 1: pip (Recommended)

pip install clipboard-mcp

Consider using a virtual environment to avoid dependency conflicts:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install clipboard-mcp

Option 2: uv (Lightweight, for trying it out)

Run directly with uv (no pip installation required):

# One-time execution
uv run --from clipboard-mcp clipboard-mcp

# Or clone and run from source
git clone https://github.com/gabiteodoru/clipboard-mcp.git
cd clipboard-mcp
uv run clipboard-mcp

Option 3: From Source

git clone https://github.com/gabiteodoru/clipboard-mcp.git
cd clipboard-mcp
pip install -e .

Usage

With Claude CLI

After pip installation:

claude mcp add --scope user clipboard-mcp clipboard-mcp

With uv (no installation):

claude mcp add --scope user clipboard-mcp "uv run --from clipboard-mcp clipboard-mcp"

Or from source directory:

claude mcp add --scope user clipboard-mcp "uv run /path/to/clipboard-mcp"

With Claude Desktop

Add to your Claude Desktop configuration file.

Configuration file locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

After pip installation:

{
  "mcpServers": {
    "clipboard": {
      "command": "clipboard-mcp"
    }
  }
}

With uv (no installation):

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

From source directory:

{
  "mcpServers": {
    "clipboard": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/clipboard-mcp",
        "run",
        "clipboard-mcp"
      ]
    }
  }
}

Available Tools

Once configured, Claude will have access to these tools:

read_clipboard() - Reads the current clipboard content
write_clipboard(text) - Writes text to the clipboard

Example Interactions

With this MCP server running, you can ask Claude to:

"Read what's in my clipboard"
"Copy this code snippet to my clipboard"
"Save this output to my clipboard so I can paste it elsewhere"

How It Works

This MCP server uses the pyperclip library to interact with your system clipboard. It provides a secure bridge between Claude and your clipboard through the Model Context Protocol.

Troubleshooting

Linux: "Failed to read clipboard" errors

Problem: Missing system clipboard utilities

Solution: Install the required tools:

# For X11
sudo apt install xclip xsel

# For Wayland
sudo apt install wl-clipboard

# Or use PyQt5 as fallback (larger dependency)
pip install PyQt5

Linux: Running in a headless environment

Problem: No display server available (e.g., SSH session, Docker)

Solution: Clipboard operations require a display server. For headless environments, consider:

Using X11 forwarding: ssh -X user@host
Running a virtual display with Xvfb
Using alternative data transfer methods

Verification

Test the installation manually:

# Test reading clipboard (copy something first)
python -c "import pyperclip; print(pyperclip.paste())"

# Test writing to clipboard
python -c "import pyperclip; pyperclip.copy('Hello from Python')"

Getting Help

If you encounter issues:

Check that dependencies are installed for your platform
Verify pyperclip works independently (see verification above)
Open an issue with details about your platform and error messages

Requirements

Python 3.8 or higher
mcp - Model Context Protocol SDK
pyperclip - Cross-platform clipboard library

Platform-Specific Requirements

Platform	Requirements	Status
macOS	Built-in (pbcopy/pbpaste)	✅ No setup needed
Windows	Built-in (clip.exe, PowerShell)	✅ No setup needed
Linux X11	xclip or xsel	⚠️ Manual install required
Linux Wayland	wl-clipboard	⚠️ Manual install required
WSL	Windows clipboard tools	✅ Usually pre-installed

Security & Privacy

This server only accesses clipboard content when explicitly requested by Claude
No clipboard data is stored or transmitted except when you ask Claude to read/write
All operations are local to your machine