Cut Copy Paste MCP

🚀 MCP Cut-Copy-Paste Clipboard Server

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

🚀 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 following 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 below).
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 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)

✨ Features

• 🎯 6 MCP Tools: copy_lines, cut_lines, paste_lines, show_clipboard, undo_last_paste, get_operation_history.
• 📋 Session-Based Clipboard: Each session maintains an 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 a 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

💻 Usage Examples

Basic Usage

The following examples demonstrate how to use the MCP tools:

copy_lines

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

cut_lines

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

paste_lines (single target)

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

paste_lines (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
      }
    ]
  }
}

show_clipboard

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

undo_last_paste

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

get_operation_history

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

Advanced Usage

The advanced usage mainly refers to the usage patterns in different scenarios:

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.

📚 Documentation

MCP Tools Reference

1. copy_lines

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

Parameters:

• file_path (string, required): Path to the 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 the source, saves to the clipboard).

Parameters:

• file_path (string, required): Path to the 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 the 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 the 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
      }
    }
  ]
}

How It Works

What It Does

Think of this as a smart clipboard for code that AI assistants (like Claude) can use. Instead of copying entire files, it can:

• Copy specific lines from a file (like lines 10 - 25).
• Cut lines (remove them from the original file).
• Paste those lines to one or multiple files.
• Undo if you made a mistake.

The Communication Layer

• Uses the MCP (Model Context Protocol) - a standardized way for AI assistants to talk to tools.
• Uses stdio (standard input/output) - the AI sends JSON messages and gets JSON responses back.
• Library: @modelcontextprotocol/sdk (the official MCP toolkit).

The Storage System

When you copy or cut something, it needs to be stored somewhere:

• Uses a SQLite database (a simple file - based database).
• Library: better - sqlite3 (a fast, reliable SQLite library for Node.js).
• Stores:
  • What you copied (the actual code).
  • Where it came from (file path, line numbers).
  • Session info (so multiple AIs don't interfere with each other).
  • History for undo functionality.

The File Operations

All the actual reading and writing of files uses:

• The Node.js built - in fs module (filesystem operations).
• No external libraries are needed for basic file reading/writing!
• The code:
  • Reads files line by line.
  • Inserts or deletes specific line ranges.
  • Preserves line endings (Windows vs Unix style).

Operation Flow Examples

Copy Operation:

1. AI says: "Copy lines 10 - 20 from myfile.js".
2. Server reads the file using Node's fs.readFileSync().
3. Extracts lines 10 - 20 from the file.
4. Saves them to the SQLite database (your "clipboard").
5. Returns the copied text back to the AI.

Paste Operation:

1. AI says: "Paste to line 5 in otherfile.js".
2. Server retrieves the clipboard from the SQLite database.
3. Takes a snapshot of the target file (for undo later).
4. Reads the file, inserts the lines at position 5.
5. Writes the modified file back using fs.writeFileSync().
6. Saves the undo information to the database.

Undo Operation:

1. AI says: "Undo that paste".
2. Server looks up the last paste in the database.
3. Finds the saved snapshot from before the paste.
4. Restores the file to its original state.
5. If it was from a "cut", also restores the source file!

Key Libraries

The Clever Parts

1. Session Isolation: Each AI assistant gets its own clipboard, so they don't interfere with each other.
2. Full Snapshots: Before pasting, it saves the entire file - this makes undo super reliable.
3. Line - by - Line: It works with line numbers (like "line 10 - 20"), which matches how developers think about code.
4. Binary Detection: Refuses to work with images/PDFs - only text files.

What Makes It Special

Unlike a regular clipboard:

• ✅ Remembers where the code came from.
• ✅ Can paste to multiple files at once.
• ✅ Has reliable undo (even for cut operations).
• ✅ Works across files and projects.
• ✅ Keeps a history of all operations.

In essence: It's a sophisticated clipboard that speaks the AI's language (MCP), uses a database to remember everything (SQLite), and does all the file reading/writing using basic Node.js tools. The magic is in how it coordinates these pieces to provide reliable cut/copy/paste/undo operations for AI coding assistants!

Architecture

Core Components

1. MCP Server - Handles protocol communication and tool registration.
2. Session Manager - Manages session state and clipboard buffers.
3. File Handler - Reads and writes file operations with line number support.
4. Operation Logger - SQLite - based operation history for undo functionality.
5. Clipboard Manager - Manages the clipboard buffer per session.

Database Schema

The server uses SQLite with 4 main tables:

• sessions - Session tracking with activity timestamps.
• clipboard_buffer - Per - session clipboard state.
• operations_log - Audit trail of all operations.
• paste_history - Enables undo functionality.

Data Directory

By default, the database is stored at:

• macOS/Linux: ~/.mcp - clipboard/clipboard.db.
• Windows: %USERPROFILE%\.mcp - clipboard\clipboard.db.

CLI Usage

# Start the MCP server
cut - copy - paste - mcp

# Show help
cut - copy - paste - mcp --help

# Show version
cut - copy - paste - mcp --version

Configuration

Claude Desktop / Claude Code

Add to your MCP configuration file:

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

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

For local development (not yet published to npm):

{
  "mcpServers": {
    "clipboard": {
      "command": "node",
      "args": ["/absolute/path/to/cut - copy - paste - mcp/dist/cli.js"]
    }
  }
}

Cursor IDE

Add to your Cursor MCP settings file:

macOS/Linux: ~/.cursor/mcp_config.json Windows: %USERPROFILE%\.cursor\mcp_config.json

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

Cline (VS Code Extension)

Add to your Cline MCP settings:

1. Open VS Code Settings.
2. Search for "Cline: MCP Settings".
3. Add the configuration:

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

Session Timeout

Sessions automatically expire after 24 hours of inactivity. Expired sessions are cleaned up on server start.

AI Agent Configuration

To help your AI coding assistant use this MCP server effectively, you can provide it with usage guidelines and best practices.

Setting Up Agent Instructions

The file contains comprehensive guidelines for AI agents, including:

• Detailed tool documentation with use cases.
• Workflow patterns for common refactoring tasks.
• Best practices for clipboard operations.
• Error handling guidance.

How to configure your agent:

1. Claude Desktop / Claude Code Users:
   • Create or edit CLAUDE.md in your project root.
   • Copy the contents of docs/AGENTIC_USAGE.md into this file.
   • Claude will automatically use these instructions when working in your project.
2. Cursor IDE Users:
   • Create or edit .cursorrules or AGENTS.md in your project root.
   • Copy the contents of docs/AGENTIC_USAGE.md into this file.
   • Cursor will use these guidelines for AI interactions.
3. Other MCP Clients:
   • Consult your client's documentation for custom instructions/rules files.
   • Add the contents of docs/AGENTIC_USAGE.md to the appropriate configuration.

What This Provides

With these instructions configured, your AI assistant will:

• Know when to use clipboard operations vs. native file editing.
• Follow established workflow patterns for refactoring.
• Verify clipboard contents before pasting.
• Use multi - target paste for boilerplate distribution.
• Handle errors gracefully.

Example: When you ask "Refactor the authentication logic into a separate module", the AI will know to:

1. Use cut_lines to extract the code.
2. Use show_clipboard to verify what was captured.
3. Use paste_lines to insert it in the new location.
4. Offer to undo_last_paste if the result isn't correct.

🔧 Technical Details

Design Decisions

1. ✅ SQLite over JSON files - Provides ACID guarantees, easier querying.
2. ✅ stdio transport - Simpler for local development, sufficient for MCP.
3. ✅ 1 - indexed line numbers - Matches editor conventions.
4. ✅ Single undo level - Keeps complexity manageable for v1.
5. ✅ Return content on copy/cut - Provides immediate feedback to LLM.

Limitations

• 📝 Text files only - Binary files are rejected.
• 📝 Single undo level - Only the last paste operation can be undone.
• 📝 10MB clipboard limit - Maximum clipboard content size.
• 📝 stdio transport only - HTTP transport planned for v2.

Roadmap

v1.0 (Current)

• ✅ Core clipboard operations.
• ✅ Session management.
• ✅ Undo support.
• ✅ Operation history.

v2.0 (Planned)

• 🔮 HTTP transport support.
• 🔮 Multi - level undo stack.
• 🔮 Large file optimization (streaming).
• 🔮 Authentication support.

📄 License

This project is under the MIT License. See the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

• Built with Model Context Protocol SDK.
• Inspired by clipboard operations in modern code editors.
• Motivated by Kix Panganiban's article "Two things LLM coding agents are still bad at" highlighting the need for proper cut/copy/paste tools in AI coding workflows.
• Developed using strict TDD principles.

Made with ❤️ for AI - assisted coding workflows

Security Considerations

• Encrypted Storage: Clipboard entries are encrypted at rest with AES - 256 - GCM using a 32 - byte key stored in ~/.mcp - clipboard/clipboard.key (or alongside any custom --db - path).
• Key Management: The key is created automatically the first time the server runs; rotate it by replacing the file and clearing stale sessions.
• File Permissions: The server enforces 700/600 permissions on the clipboard directory and database/key files; verify these remain intact if you relocate them.
• Path Access Control: By default, the server can access all filesystem paths. To restrict access, create ~/.mcp - clipboard/paths.allow with allowed path patterns. See Path Access Control Documentation for configuration examples.
• Database Location: You can override the database location (and thus the key location) via the DatabaseManager constructor or CLI flag in future releases.

Quick Setup for Restricted Access

To limit the server to your current project only, create ~/.mcp - clipboard/paths.allow:

# Allow only your project directory
/Users/username/my - project/**

# Exclude common directories
!**/node_modules/**
!**/.git/**

See Path Access Control Documentation for more examples and best practices.