MCP Cut-Copy-Paste Clipboard Server

A Model Context Protocol (MCP) server that provides clipboard-style operations for AI-assisted coding agents. Cut, copy, paste, and undo code blocks across files with full audit trail and session management.

Features

• 🎯 6 MCP Tools: copy_lines, cut_lines, paste_lines, show_clipboard, undo_last_paste, get_operation_history
• 📋 Session-Based Clipboard: Each session maintains independent clipboard state
• ↩️ Smart Undo Support: Revert paste operations with complete file snapshots - automatically restores cut source files
• 📊 Audit Trail: SQLite-based operation logging for debugging
• 🔐 Encrypted Clipboard Storage: AES-256-GCM encrypted payloads with per-installation keys stored beside the SQLite DB
• 🛡️ Path Access Control: Optional .gitignore-style allowlist to restrict filesystem access (docs)
• 🔒 Session Management: Automatic cleanup with 24-hour timeout
• 🚀 NPX Ready: Easy installation and updates via npm
• 🌍 Unicode Support: Full support for international characters and emoji
• 🛡️ Binary File Detection: Automatically rejects PNG, PDF, JPEG, GIF, and other binary formats
• 📏 Flexible Line Insertion: Supports paste at line 0 (beginning of file)

Installation

Via NPX (Recommended)

npx cut-copy-paste-mcp

Via NPM

npm install -g cut-copy-paste-mcp
cut-copy-paste-mcp

Local Development

git clone https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp.git
cd cut-copy-paste-mcp
npm install
npm run build
node dist/cli.js

Quick Start

For Claude Code / Claude Desktop Users

1. Configure the MCP server:

   • Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
   • Or %APPDATA%\Claude\claude_desktop_config.json (Windows)
   • Add the configuration:

   {
     "mcpServers": {
       "clipboard": {
         "command": "npx",
         "args": ["cut-copy-paste-mcp"]
       }
     }
   }
   

2. Restart Claude Desktop/Code to load the MCP server

3. Verify the tools are available:

   • In your conversation, you should see clipboard tools available
   • Try: "Show me the available clipboard tools"

4. Start using the clipboard:

   • "Copy lines 10-25 from src/utils.ts"
   • "Show me what's in the clipboard"
   • "Paste the clipboard to line 5 in src/helpers.ts"

For Other MCP Clients

1. Install the server (see Installation above)
2. Configure your MCP client to connect to cut-copy-paste-mcp
3. Configure AI agent instructions (optional but recommended):
   • Copy the usage guidelines from docs/AGENTIC_USAGE.md into your agent's instruction files:
     • Claude Desktop/Code: Add to CLAUDE.md in your project root
     • Cursor IDE: Add to .cursorrules or AGENTS.md in your project
     • Other agents: Add to your agent's custom rules/instructions file
   • These guidelines help the AI understand when and how to use clipboard operations effectively
4. Start using clipboard operations in your AI coding workflow

Example Workflow

You/AI: "I need to refactor the authentication logic.
      Copy lines 45-80 from src/auth/old-auth.ts"

AI: [Uses copy_lines tool]
    ✓ Copied 36 lines from src/auth/old-auth.ts:45-80

You/AI: "Now paste this into a new file src/auth/token-handler.ts at line 1"

AI: [Uses paste_lines tool]
    ✓ Pasted to src/auth/token-handler.ts:1

You/AI: "Actually, I want to undo that and paste it somewhere else"

AI: [Uses undo_last_paste tool]
    ✓ Undone paste operation, restored 1 file(s)

MCP Tools Reference

1. copy_lines

Copy lines from a file to session clipboard without modifying the source.

Parameters:

• file_path (string, required): Path to source file
• start_line (number, required): Starting line number (1-indexed)
• end_line (number, required): Ending line number (inclusive)

Example:

{
  "tool": "copy_lines",
  "arguments": {
    "file_path": "src/utils/helpers.ts",
    "start_line": 10,
    "end_line": 25
  }
}

Returns:

{
  "success": true,
  "content": "...",
  "lines": ["..."],
  "message": "Copied 16 line(s) from src/utils/helpers.ts:10-25"
}

2. cut_lines

Cut lines from a file (removes from source, saves to clipboard).

Parameters:

• file_path (string, required): Path to source file
• start_line (number, required): Starting line number (1-indexed)
• end_line (number, required): Ending line number (inclusive)

Example:

{
  "tool": "cut_lines",
  "arguments": {
    "file_path": "src/legacy/old-module.ts",
    "start_line": 50,
    "end_line": 75
  }
}

Returns:

{
  "success": true,
  "content": "...",
  "lines": ["..."],
  "message": "Cut 26 line(s) from src/legacy/old-module.ts:50-75"
}

3. paste_lines

Paste clipboard content to one or more locations.

Parameters:

• targets (array, required): Array of paste targets
  • file_path (string): Target file path
  • target_line (number): Line number to paste at (1-indexed)

Example (single target):

{
  "tool": "paste_lines",
  "arguments": {
    "targets": [
      {
        "file_path": "src/components/NewComponent.tsx",
        "target_line": 20
      }
    ]
  }
}

Example (multiple targets):

{
  "tool": "paste_lines",
  "arguments": {
    "targets": [
      {
        "file_path": "src/services/auth.ts",
        "target_line": 5
      },
      {
        "file_path": "src/services/api.ts",
        "target_line": 8
      },
      {
        "file_path": "src/services/storage.ts",
        "target_line": 3
      }
    ]
  }
}

Returns:

{
  "success": true,
  "pastedTo": [
    { "file": "src/components/NewComponent.tsx", "line": 20 }
  ],
  "message": "Pasted to 1 location(s)"
}

4. show_clipboard

Display current clipboard contents with metadata.

Parameters: None

Example:

{
  "tool": "show_clipboard",
  "arguments": {}
}

Returns:

{
  "hasContent": true,
  "content": "...",
  "sourceFile": "src/utils/helpers.ts",
  "startLine": 10,
  "endLine": 25,
  "operationType": "copy",
  "copiedAt": 1699564800000
}

5. undo_last_paste

Undo the most recent paste operation. If the paste came from a cut operation, both the paste target(s) AND the cut source are restored to their original state.

Parameters: None

Example:

{
  "tool": "undo_last_paste",
  "arguments": {}
}

Returns:

{
  "success": true,
  "restoredFiles": [
    { "file": "src/components/NewComponent.tsx", "line": 20 },
    { "file": "src/legacy/old-module.ts", "line": 0 }
  ],
  "message": "Undone paste operation, restored 2 file(s)"
}

Behavior:

• Copy → Paste → Undo: Restores only the paste target file(s)
• Cut → Paste → Undo: Restores both the paste target(s) AND the cut source file

6. get_operation_history

Retrieve operation history for debugging.

Parameters:

• limit (number, optional): Max number of operations to return (default: 10)

Example:

{
  "tool": "get_operation_history",
  "arguments": {
    "limit": 5
  }
}

Returns:

{
  "operations": [
    {
      "operationId": 42,
      "operationType": "paste",
      "timestamp": 1699564800000,
      "details": {
        "targetFile": "src/components/NewComponent.tsx",
        "targetLine": 20
      }
    }
  ]
}

Usage Patterns

Pattern 1: Refactoring - Extract Function

1. Identify code to extract → Analyze file and find lines to move
2. Cut the code           → Use cut_lines to remove from original location
3. Verify clipboard       → Use show_clipboard to confirm content
4. Paste to new location  → Use paste_lines to insert at new location
5. Verify result          → Check both files for correctness

Pattern 2: Copying Boilerplate

1. Find source code       → Identify reusable code pattern
2. Copy the pattern       → Use copy_lines to capture boilerplate
3. Identify targets       → List all files needing this pattern
4. Multi-paste           → Use paste_lines with multiple targets
5. Verify                → Spot-check pasted content

Pattern 3: Moving Code Between Files

1. Cut from source       → Use cut_lines to remove code
2. Paste to destination  → Use paste_lines to insert
3. Verify both files     → Check source is cleaned up
4. Update references     → Fix imports if needed

Pattern 4: Safe Experimentation

1. Copy code for testing → Use copy_lines to capture current state
2. Paste to test location → Create experimental version
3. Test changes          → Make modifications
4. Decide                → Use undo_last_paste if unsuccessful

Pattern 5: Undoing Cut Operations

1. Cut code from source     → Use cut_lines (removes from source)
2. Paste to destination     → Use paste_lines (adds to destination)
3. Realize mistake          → Decide to revert the move
4. Undo paste operation     → Use undo_last_paste
5. Result                   → Both source AND destination restored to original state

Note: When you undo a paste from a cut operation, the server automatically restores BOTH files - the paste target(s) are restored, and the cut source is restored with the lines that were removed.

---