clipboard-mcp/README.md

A Model Context Protocol (MCP) server that provides a tool for taking screenshots of websites.

# Clipboard MCP: Give Your AI a Clipboard 📋

[![NPM Version](https://img.shields.io/npm/v/clipboard-mcp?style=flat-square)](https://www.npmjs.com/package/clipboard-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)

Your AI assistant can generate code, write prose, and answer complex questions. But when it comes to placing that output directly where you need it—on your system clipboard—it hits a wall.

**Clipboard MCP bridges that gap.**

It's a simple, secure tool that exposes a single capability to your AI: copying text to your clipboard. Now, your assistant can not only generate a code snippet but also place it on your clipboard, ready for you to paste into your editor, all in one seamless step.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
  - [Method 1: Desktop Extension](#method-1-desktop-extension)
  - [Method 2: Manual JSON Configuration](#method-2-manual-json-configuration)
- [Usage](#usage)
  - [Example Prompts](#example-prompts)
  - [Tool Reference: `clipboard`](#tool-reference-clipboard)
  - [Error Handling](#error-handling)
- [Development & Contributing](#development--contributing)

## Features

*   **Simple & Secure:** Exposes a single, safe `clipboard` tool.
*   **Cross-Platform:** Works wherever Node.js and `clipboardy` are supported.
*   **Seamless Integration:** Allows AI assistants to copy text to the user's clipboard with a simple command.
*   **Structured Output:** Returns a clear JSON object indicating success or failure.

## Installation

You can install Clipboard MCP in two ways, depending on your preference and client application.

### Method 1: Desktop Extension

This is the easiest way to get started. It allows for one-click installation in compatible clients like Claude Code.

1.  **[Download the latest `clipboard-mcp.dxt` file from the Releases page](https://github.com/gourraguis/clipboard-mcp/releases)**.
2.  Open the `.dxt` file with your client application. The client will handle the rest.

### Method 2: Manual JSON Configuration

This method uses `npx` to download and run the package on-demand. It's ideal for command-line usage or for developers who prefer not to install the extension directly.

To use this method, add the following JSON to your client's configuration file:

```json
{
  "mcpServers": {
    "clipboard": {
      "command": "npx",
      "args": ["-y", "clipboard-mcp"]
    }
  }
}
```

**Configuration File Locations:**
*   **For Claude Desktop:** `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **For Gemini CLI:** `~/.gemini/settings.json`
*   **For Cursor IDE:** Your user `settings.json` file.

## Usage

Once integrated, you can use prompts like these with your AI assistant.

### Example Prompts

Here are a few examples of how you can use Clipboard MCP.

> "Generate a UUID and copy it to my clipboard."

> "Write a Python function to calculate the factorial of a number and copy it to my clipboard."

> "What's the git command to squash the last 3 commits? Copy the command to my clipboard."

### Tool Reference: `clipboard`

| Name   | Type     | Required | Description                             |
|--------|----------|----------|-----------------------------------------|
| `text` | `string` | Yes      | The text to copy to the user's clipboard. |

**Returns:** A JSON object indicating success or failure.
```json
{
  "success": true,
  "message": "Text successfully copied to clipboard."
}
```

### Error Handling

If the tool encounters an error, it will return a JSON object with the `isError` flag set to `true` and a descriptive error message.

```json
{
  "success": false,
  "error": "Failed to copy to clipboard: [error details]"
}
```

## Development & Contributing

To contribute to this project:

1.  Clone the repository: `git clone https://github.com/gourraguis/clipboard-mcp.git`
2.  Install dependencies: `cd clipboard-mcp && npm install`
3.  Build the project: `npm run build`
4.  To test your local build, use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
    ```bash
    npx @modelcontextprotocol/inspector node dist/main.js
    ```