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)

Via NPM

Local Development

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

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:

Returns:

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:

Returns:

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):

Example (multiple targets):

Returns:

4. show_clipboard

Display current clipboard contents with metadata.

Parameters: None

Example:

Returns:

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:

Returns:

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:

Returns:

Usage Patterns

Pattern 1: Refactoring - Extract Function

Pattern 2: Copying Boilerplate

Pattern 3: Moving Code Between Files

Pattern 4: Safe Experimentation

Pattern 5: Undoing Cut Operations

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.

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 SQLite database (a simple file-based database)

• Library: better-sqlite3 (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:

• Node.js built-in (filesystem operations)

• No external libraries 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:

Paste Operation:

Undo Operation:

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 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 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

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

For local development (not yet published to npm):

Cursor IDE

Add to your Cursor MCP settings file:

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

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:

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 docs/AGENTIC_USAGE.md 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

Best Practices

1. ✅ Always verify clipboard - Use show_clipboard before paste operations

2. ✅ Use multi-paste for patterns - Apply same code to multiple files efficiently

3. ✅ Leverage undo - Don't hesitate to paste; you can always undo

4. ✅ Check operation history - Use get_operation_history to debug issues

5. ✅ Mind line numbers - Remember line numbers are 1-indexed

6. ✅ Complete sequences - Finish copy/cut/paste/undo before starting new operations

Error Handling

The server provides clear error messages for common issues:

• ❌ File not found - "Copy failed: ENOENT: no such file or directory"

• ❌ Invalid line range - "Invalid line range: start_line must be <= end_line"

• ❌ Empty clipboard - "Clipboard is empty"

• ❌ No paste to undo - "No paste operation to undo"

Development

Running Tests

Building

Project Structure

Testing

The project follows strict Test-Driven Development (TDD) with:

• 213 passing tests across 12 test suites

• 90%+ code coverage target

• Unit tests for all core components

• Integration tests for complete workflows

• Edge case tests for binary files, Unicode, large files, and more

• Dedicated tests for cut-paste-undo workflows

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 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

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Write tests following TDD principles (RED → GREEN → REFACTOR)

4. Commit your changes (git commit -m 'Add amazing feature')

5. Push to the branch (git push origin feature/amazing-feature)

6. Open a Pull Request

Security

• ✅ Path access control - Optional allowlist to restrict filesystem operations (details)

• ✅ Encrypted storage - AES-256-GCM encryption for clipboard data at rest

• ✅ Path validation - Prevents directory traversal attacks

• ✅ Input sanitization - All inputs validated before operations

• ✅ No sensitive data in errors - Error messages don't leak file contents

• ✅ File size limits - 10MB maximum clipboard size

For detailed security information, see Path Access Control Documentation.

License

MIT License - see 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:

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