clipboard-mcp 0.1.3

MCP Server for system clipboard integration

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:

1. Check that dependencies are installed for your platform
2. Verify pyperclip works independently (see verification above)
3. 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

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub Repository
• Issue Tracker
• Model Context Protocol Documentation