mcp-clipboard

AI 어시스턴트가 시스템 클립보드에 직접 접근할 수 있게 해주는 MCP 서버입니다. 복사한 내용을 읽거나, 깔끔한 텍스트를 클립보드에 바로 쓸 수 있습니다. Claude Code, Claude Desktop, Cursor, Windsurf 등 모든 MCP 호환 클라이언트에서 작동합니다.

왜 필요한가요?

붙여넣기 시 구조 손실

Google Sheets나 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 저장소에서 반복적으로 보고된 문제(이슈 #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.

또한 플랫폼별 클립보드 도구가 필요합니다:

플랫폼 상태: Wayland를 사용하는 Linux는 테스트를 거쳤으며 활발히 사용 중입니다. 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로 지정됩니다. 빈 셀은 건너뛰며, 헤더 행은 추론에서 제외됩니다.

이는 Claude에게 SQL CREATE TABLE 문, Pandas dtype 매핑 또는 유효성 검사 규칙을 위해 표 데이터를 전달할 때 유용합니다. Claude는 데이터에서 추측하는 대신 유형을 미리 알 수 있습니다.

안정적인 트리거를 위한 팁

서버에는 클라이언트에게 클립보드 도구를 언제 사용할지 알려주는 MCP 지침이 포함되어 있지만, 결과는 모델과 클라이언트에 따라 다를 수 있습니다. 에이전트가 의도를 파악하지 못하면 명시적으로 "그걸 내 클립보드에 복사해줘" 또는 "내가 복사한 내용을 읽어줘"라고 말하는 것이 가장 확실합니다.

사용자 지정 시스템 프롬프트(예: Claude Desktop 프로젝트 또는 사용자 지정 에이전트)에 접근할 수 있는 경우, 동작을 강화할 수 있습니다:

사용자가 출력을 복사하라고 요청하면 clipboard_copy를 사용하여 시스템 클립보드에 쓰세요. 사용자가 대화에 없는 데이터를 참조하면 clipboard_paste를 사용하여 클립보드를 확인하세요.

콘텐츠 처리

작동 원리

1. 플랫폼 감지: 시작 시 서버가 클립보드 백엔드(Wayland, X11, macOS 또는 Windows)를 감지하고 적절한 시스템 명령을 선택합니다.

2. 읽기 (clipboard_paste): 플랫폼의 클립보드 읽기 명령을 호출합니다. 먼저 text/html을 시도하고(Google Sheets와 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