mcp-clipboard

AIアシスタントがシステムクリップボードに直接アクセスできるようにするMCPサーバーです。コピーした内容を読み取ったり、クリーンなテキストを直接書き込んだりできます。Claude Code、Claude Desktop、Cursor、Windsurfなど、MCP互換のあらゆるクライアントで動作します。

なぜこれが必要なのか

貼り付けによる構造の喪失

GoogleスプレッドシートやExcelからセルをコピーしてチャット入力欄に貼り付けると、表形式の構造（行と列）が失われてしまいます。区切り文字のないフラットな文字列として貼り付けられるため、モデルはどこでセルが終わり、どこで次が始まるかを推測しなければならず、しばしば誤った推測をしてしまいます。

mcp-clipboardは構造を保持します。 貼り付ける代わりに、アシスタントに「クリップボードを読み取って」と伝えてください。サーバーが直接クリップボードを読み取り、スプレッドシートアプリがクリップボードに配置するHTMLから表形式データを検出し、適切にフォーマットされたMarkdownテーブル、JSON、またはCSVとして返します。構造が失われることも、推測に頼ることもありません。

おまけ：Claude Codeからのコピーも修正

Claude Codeのターミナルレンダラーは、すべての出力に2文字のパディング、約80列での強制改行、末尾の空白を追加します。ターミナルからテキストを選択してコピーすると、これらの不要な要素も一緒にコピーされてしまいます：

  echo "this is a long command that wraps and
  breaks when you paste it because of the hard
  newlines and leading spaces"

これはclaude-codeリポジトリで繰り返し報告されており（issue #4686, #6827, #7670, #13378, #15199, #25040, #25427, #26016）、多数の賛同を得ていますが、修正はリリースされていません。

mcp-clipboardはこの問題を完全に回避します。 ターミナルからテキストをコピーする代わりに、Claude Codeにクリップボードへ書き込むよう依頼してください：

「そのコマンドをクリップボードにコピーして」

Claude Codeが clipboard_copy を呼び出し、クリーンなテキストを直接システムクリップボードに書き込むため、必要な場所に貼り付けるだけです。パディングも、強制改行も、クリーンアップも不要です。

ヒント: これを自動化するには、プロジェクトまたはグローバルな CLAUDE.md に以下の行を追加してください：

When you produce a shell command for the user to run, also copy it to the clipboard using clipboard_copy.

これで、Claude Codeが提案するすべてのコマンドが、依頼しなくても自動的にコピーされるようになります。

ツール

セットアップ

前提条件

Python 3.11以上 および以下のいずれか：uv（推奨）、pipx、またはpip。

また、プラットフォーム固有のクリップボードツールも必要です：

プラットフォームのステータス: Linux (Wayland) はテスト済みで積極的に使用されています。X11、macOS、Windowsの実装は完了していますが、実機でのテストは行われていません。バグレポートやPRを歓迎します。

Claude Code

claude mcp add clipboard --scope user -- uvx mcp-clipboard

Claude Desktop

Claude Desktopの設定に追加してください：

• Linux: ~/.config/Claude/claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "clipboard": {
      "command": "uvx",
      "args": ["mcp-clipboard"]
    }
  }
}

その他のMCPクライアント

MCP stdioサーバーをサポートするクライアントであれば、mcp-clipboardを使用できます。最も簡単な方法は uvx mcp-clipboard です。MCPサーバーの登録方法については、各クライアントのドキュメントを参照してください。

ソースからのインストール

PyPIからインストールする代わりにローカルクローンを使用したい場合：

git clone https://github.com/cmeans/mcp-clipboard.git
cd mcp-clipboard
uv sync

その後、クライアントでローカルインストール先を指定してください：

{
  "mcpServers": {
    "clipboard": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mcp-clipboard",
        "mcp-clipboard"
      ]
    }
  }
}

環境変数

環境変数は設定内の "env" キーを介して渡すことができます。

ほとんどのLinuxユーザーはこれらを設定する必要はありません。自動検出が失敗する場合（複数のコンポジタ、非標準のソケットパス、コンテナ環境など）にのみ上書きしてください。

使用方法

クリップボードの読み取り

何か（スプレッドシートのセル、コード、テキスト、URL、JSON、画像）をコピーしてから、以下のように伝えます：

• 「クリップボードを貼り付けて」

• 「クリップボードを読み取って」

• 「クリップボードには何が入っている？」

• 「データをコピーしたから見てみて」

アシスタントが clipboard_paste を呼び出し、構造を保持した状態でコンテンツを返します。

クリップボードへの書き込み

エージェントがコマンド、コードブロック、または他の場所で使用したいテキストを生成したとき：

• 「それをクリップボードにコピーして」

• 「そのコマンドをクリップボードに入れて」

• 「それをHTMLとしてコピーして」（text/html を書き込むため、リッチテキストアプリでフォーマットを保持して貼り付けられます）

エージェントが clipboard_copy を呼び出し、クリーンなテキストが直接システムクリップボードに送られます。ターミナルのレンダリングによる不要な要素はなく、クリーンなテキストのみです。これは特にClaude Codeで役立ちます（上記を参照）。

ヒント: 自動コピー動作。 デフォルトでは、エージェントは依頼されたときのみクリップボードにコピーします。コマンドやコードブロックを自動的にコピーしたい場合は、システムプロンプト（Claude DesktopプロジェクトやClaude Codeの CLAUDE.md など）に以下を追加してください：

ユーザーが他の場所に貼り付ける可能性のあるコマンドやコードブロックを出力する場合は、clipboard_copy を使用してプロアクティブにクリップボードへコピーしてください。

テーブルの出力フォーマット

クリップボードに表形式データが含まれている場合、output_format でフォーマットを制御できます：

例:

• 「クリップボードをSlack形式で読み取って」 → output_format=slack

• 「クリップボードをJiraテーブルに変換して」 → output_format=jira

• 「それをHTMLでちょうだい」 → output_format=html

テーブルのスキーマ推論

include_schema=true を追加すると、テーブルと一緒に列タイプの概要を取得できます：

「スキーマ付きでクリップボードを読み取って」

推論されるタイプ: integer（整数）、float（浮動小数点）、currency（通貨）、percentage（パーセンテージ）、date（日付）、boolean（真偽値）、text（テキスト）。列ごとに多数決を採用します。空でないセルの半分以上を占めるタイプがない場合、その列は text と判定されます。空のセルはスキップされ、ヘッダー行は推論から除外されます。

これは、SQLの CREATE TABLE 文、Pandasの dtype マッピング、または検証ルールをClaudeに渡す際に役立ちます。Claudeはデータから推測する代わりに、事前にタイプを取得できます。

信頼性の高いトリガーのためのヒント

サーバーには、いつクリップボードツールを使用すべきかをクライアントに伝えるMCP指示が含まれていますが、結果はモデルやクライアントによって異なります。エージェントが意図を汲み取らない場合は、「それをクリップボードにコピーして」や「コピーした内容を読み取って」のように明示的に指示するのが最も確実です。

カスタムシステムプロンプト（Claude Desktopプロジェクトやカスタムエージェントなど）にアクセスできる場合は、動作を強化できます：

ユーザーがコピーを依頼したときは、clipboard_copy を使用してシステムクリップボードに書き込んでください。ユーザーが会話に含まれていないデータを参照したときは、clipboard_paste を使用してクリップボードを確認してください。

コンテンツの取り扱い

仕組み

1. プラットフォーム検出: 起動時に、サーバーはクリップボードのバックエンド（Wayland, X11, macOS, Windows）を検出し、適切なシステムコマンドを選択します。

2. 読み取り (clipboard_paste): プラットフォームのクリップボード読み取りコマンドを呼び出します。まず text/html を試行し（GoogleスプレッドシートやExcelはクリップボードに <table> マークアップを配置するため）、Pythonの組み込み html.parser で解析します。次に text/plain のタブ区切り値、続いて text/rtf を試し、最後に画像を確認します。

3. 書き込み (clipboard_copy): テキストをプラットフォームのクリップボード書き込みコマンド（wl-copy, xclip -selection clipboard, pbcopy, またはPowerShellの Set-Clipboard）にパイプします。型付きコンテンツ（text/html, text/rtf など）を書き込むための mime_type パラメータをサポートしています。

4. 画像パススルー: クリップボードに画像（PNGなど）が含まれている場合、モデルが認識・分析できるbase64エンコードされたMCP画像コンテンツブロックとして返されます。

5. コンテンツ分類: 表形式以外のテキストコンテンツは、JSON、URL、コード、またはプレーンテキストとして分類され、適切なフォーマット（整形されたJSON、フェンス付きコードブロックなど）で返されます。

制限事項

• オーディオとビデオはサポートされていません。 クリップボードにオーディオやビデオが含まれている場合、サーバーはフォー