clipboard-mcp

mcp-clipboard

Um servidor MCP que dá ao seu assistente de IA acesso direto à área de transferência do seu sistema: leia o que você copiou ou escreva texto limpo diretamente nela. Funciona com qualquer cliente compatível com MCP, incluindo Claude Code, Claude Desktop, Cursor, Windsurf e outros.

Por que isso existe

Colar perde a estrutura

Quando você copia células do Google Sheets ou Excel e cola em um campo de chat, a estrutura tabular (linhas e colunas) é destruída. Ela chega como uma string plana, sem delimitadores. O modelo precisa adivinhar onde uma célula termina e a próxima começa, e muitas vezes adivinha errado.

O mcp-clipboard preserva isso. Em vez de colar, diga ao seu assistente para "ler minha área de transferência". O servidor lê a área de transferência diretamente, detecta dados tabulares a partir do HTML que os aplicativos de planilha colocam na área de transferência e os retorna como uma tabela Markdown, JSON ou CSV devidamente formatada. Sem perda de estrutura, sem adivinhação.

Bônus: também corrige a cópia do Claude Code

O renderizador de terminal do Claude Code adiciona preenchimento de 2 caracteres, quebras de linha forçadas em ~80 colunas e espaços em branco finais em toda a saída. Quando você seleciona e copia texto do terminal, esses artefatos vêm junto:

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

Isso foi relatado repetidamente no repositório claude-code (issues #4686, #6827, #7670, #13378, #15199, #25040, #25427, #26016) com dezenas de votos positivos e nenhuma correção lançada.

O mcp-clipboard contorna o problema completamente. Em vez de copiar texto do terminal, peça ao Claude Code para colocá-lo na sua área de transferência:

"Copie esse comando para minha área de transferência"

O Claude Code chama clipboard_copy, escreve o texto limpo diretamente na sua área de transferência do sistema, e você cola onde precisar. Sem preenchimento, sem quebras forçadas, sem limpeza.

Dica: Para tornar isso automático, adicione uma linha ao seu CLAUDE.md de projeto ou global:

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

O Claude Code então copiará todos os comandos que sugerir sem que você precise pedir.

Bônus: leia sua seleção X11/Wayland sem Ctrl-C

Os desktops Linux têm duas áreas de transferência: a CLIPBOARD, usada por Ctrl-C / Ctrl-V, e a seleção PRIMARY. PRIMARY é o texto que você tem destacado no momento, colado com o clique do meio. Ela é atualizada assim que você seleciona algo; você não precisa copiar.

O mcp-clipboard também lê PRIMARY. Passe selection="primary" para clipboard_paste, clipboard_read_raw ou clipboard_list_formats e o servidor lerá o buffer de seleção em vez da área de transferência do Ctrl-C. Alguns fluxos de trabalho que isso permite:

• Triagem no terminal. Uma mensagem de erro passa rolando, selecione-a com o mouse, pergunte ao modelo o que ela significa. Seu buffer Ctrl-C permanece intacto para o que você tinha nele.
• Seleção visual no vim / IDE. Selecione uma função com v, peça ao modelo para explicá-la ou refatorá-la.
• Leitura no navegador / PDF. Selecione um parágrafo arrastando o mouse, pergunte "o que isso está dizendo?" sem sair do fluxo de leitura.
• Fluxos de trabalho com dois buffers. Mantenha um trecho na CLIPBOARD (Ctrl-C) e puxe outro pela PRIMARY na mesma conversa.

Somente Linux. macOS e Windows não têm buffer equivalente; passar selection="primary" nessas plataformas retorna um erro claro.

Ferramentas

Ferramenta	Descrição
clipboard_paste	Ferramenta principal. Leia qualquer conteúdo da área de transferência: tabelas, texto, código, JSON, URLs, imagens. Tabelas são formatadas como Markdown/JSON/CSV; passe include_schema=true para anexar tipos de coluna inferidos. Imagens são retornadas como conteúdo de imagem que o modelo pode ver. O selection="primary" opcional lê a seleção PRIMARY do X11/Wayland (buffer de clique do meio / selecionar-texto-para-colar) em vez da área de transferência padrão do Ctrl-C.
clipboard_copy	Escreva conteúdo de texto na área de transferência do sistema. Aceita um parâmetro opcional mime_type (text/plain por padrão; também text/html, text/rtf, image/svg+xml ou qualquer text/* no Wayland/X11).
clipboard_copy_markdown	Renderize markdown para HTML e coloque ambos os formatos na área de transferência para que os destinos de colagem escolham o correto — Slack/Gmail/Notion/Discord recebem texto rico; vim/terminal recebem o código-fonte. macOS/Windows gravam ambos atomicamente; Wayland/X11 são de MIME único e gravam apenas text/html.
clipboard_copy_image	Escreva uma imagem PNG ou JPEG na área de transferência do sistema a partir de bytes codificados em base64. Pass-through sem re-codificação; os magic bytes são validados contra o MIME declarado. Use clipboard_copy para texto.
clipboard_list_formats	Liste quais tipos MIME estão atualmente na área de transferência. Aceita selection="primary" para a seleção PRIMARY do X11/Wayland.
clipboard_read_raw	Retorne o conteúdo bruto da área de transferência para um determinado tipo MIME (diagnóstico). Qualquer tipo não binário passa; apenas image/*, audio/*, video/* e application/octet-stream são rejeitados. Use clipboard_paste para imagens. Aceita selection="primary" para a seleção PRIMARY do X11/Wayland.
clipboard_version	Retorne a versão do pacote mcp-clipboard em execução como {"name": "mcp-clipboard", "version": "<x.y.z>"}. Diagnóstico. Útil para hosts que não expõem o bloco MCP padrão serverInfo ao modelo e para harnesses de teste que precisam registrar qual build atendeu a uma determinada execução.

Configuração

Passo 1: Instale um executor de pacotes Python

mcp-clipboard é um pacote Python no PyPI. Qualquer ferramenta Python que possa instalar e executar entry points de console-script funciona para executá-lo como um servidor MCP. As duas opções mais comuns são pipx e uv; ambas aparecem nos badges de contagem de instalações no topo deste README e ambas estão em uso ativo. Escolha a que você tem ou prefere:

• pipx: as instruções de instalação por plataforma estão na documentação oficial de instalação do pipx. Na maioria das distros, o pipx está disponível via gerenciador de pacotes do sistema (apt, dnf, pacman, brew, etc.).
• uv: as instruções de instalação por plataforma estão na documentação oficial de instalação do uv. A Astral documenta caminhos de gerenciador de pacotes, downloads de binários autônomos assinados e instaladores de shell para cada plataforma.

Verifique se o executor escolhido está no PATH:

pipx --version   # if you chose pipx

uv --version     # if you chose uv

O restante desta seção mostra comandos para ambos os executores; substitua pelo que você instalou.

Passo 2: Instale a ferramenta de área de transferência da plataforma (somente Linux)

macOS e Windows têm tudo o que precisam embutido. O Linux precisa de um utilitário de CLI:

Plataforma	Ferramenta	Instalação
Fedora / RHEL (Wayland)	wl-copy / wl-paste	sudo dnf install wl-clipboard
Ubuntu / Debian (Wayland)	wl-copy / wl-paste	sudo apt install wl-clipboard
Linux (X11)	xclip	sudo dnf install xclip ou sudo apt install xclip
macOS	Embutido	Sem necessidade de instalação (pbcopy / pbpaste)
Windows	Embutido	Sem necessidade de instalação (PowerShell)

Status da plataforma: Linux com Wayland é testado e usado ativamente. O Windows foi exercitado de ponta a ponta em um guest Windows QEMU (um bug real de codificação exclusivo do Windows, #129, foi encontrado e corrigido por meio desse teste na v2.5.x). As implementações X11 e macOS estão completas, mas não verificadas além dos testes unitários. Relatórios de bugs e PRs são bem-vindos.

Passo 3: Verifique se o mcp-clipboard funciona no seu sistema

Antes de conectá-lo a um cliente, confirme se o pacote instala e detecta sua plataforma corretamente. Com pipx:

pipx run mcp-clipboard --check

Ou com uv:

uvx mcp-clipboard --check

Ambas as formas buscam o pacote sob demanda sem instalação permanente (use pipx install mcp-clipboard ou uv tool install mcp-clipboard primeiro se preferir instalá-lo de forma persistente). Saída esperada:

mcp-clipboard 2.5.1
Platform: ...
Backend: ... (detected)
OK: mcp-clipboard should work on this system.

Se você vir Backend: NOT AVAILABLE, siga a dica específica da plataforma na mensagem de erro (normalmente: instale a ferramenta de área de transferência do Linux do Passo 2) e execute novamente.

Passo 4: Registre o servidor no seu cliente MCP

O host MCP inicia mcp-clipboard por meio de um par command + args. Tanto pipx quanto uv expõem um subcomando de execução única que busca e executa o pacote, então as configurações mais convenientes usam essas formas.

Claude Code

Com pipx:

claude mcp add clipboard --scope user -- pipx run mcp-clipboard

Com uv:

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

Claude Desktop

Localize o arquivo de configuração do Claude Desktop (cole o caminho na barra de endereços do seu gerenciador de arquivos para ir direto até ele):

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

Adicione uma entrada a mcpServers usando uma das formas abaixo. Com pipx:

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

Ou com uv:

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

Salve o arquivo e saia completamente e reinicie o Claude Desktop para que o novo servidor seja carregado.

Dica para Windows: O Claude Desktop armazena em cache o ambiente (incluindo PATH) desde o momento em que é iniciado. Se pipx/uvx foi instalado depois que o Claude Desktop foi iniciado, o Claude Desktop não o verá até reiniciar. Se o trecho acima produzir "Server failed to start" ou um erro do tipo "command not found" nos logs do MCP, clique com o botão direito no ícone da bandeja do Claude Desktop, escolha Quit e reabra o Claude Desktop. Fechar com o X da barra de tarefas apenas oculta a janela; o ambiente em cache ainda está lá.

Outros clientes MCP

Qualquer cliente que suporte servidores MCP stdio pode usar o mcp-clipboard. Formas comuns de execução única são pipx run mcp-clipboard e uvx mcp-clipboard; se você instalou o mcp-clipboard de forma persistente (pipx install mcp-clipboard ou uv tool install mcp-clipboard), o binário mcp-clipboard resultante em PATH também funciona como command. Consulte a documentação do seu cliente para saber como registrar servidores MCP.

Passo 5: Confirme que funciona de ponta a ponta

No seu cliente, pergunte:

O que está na minha área de transferência?

O cliente deve chamar clipboard_paste e retornar o conteúdo. Se você copiou uma seleção de planilha ou uma URL antes, verá formatada adequadamente.

Se nada acontecer ou você receber um erro de ferramenta, execute novamente --check (qualquer executor que você usou no Passo 3) para confirmar que a instalação do pacote está saudável e verifique os logs do servidor MCP do seu cliente (cada host MCP os expõe de forma diferente; consulte a documentação do seu cliente).

Instalando a partir do código-fonte

Se você preferir um clone local em vez de instalar do PyPI:

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

Em seguida, aponte seu cliente para a instalação local:

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

Variáveis de ambiente

As variáveis de ambiente podem ser passadas via a chave "env" na configuração.

Variável	Plataforma	Finalidade	Padrão
MCP_CLIPBOARD_DEBUG	Todas	Ativar log de depuração (1 para ativar)	Desativado
WAYLAND_DISPLAY	Linux (Wayland)	Nome do socket do compositor ou caminho absoluto	Detecção automática
XDG_RUNTIME_DIR	Linux (Wayland)	Diretório que contém o socket Wayland	/run/user/<uid>
XDG_SESSION_TYPE	Linux	Dica de tipo de sessão (wayland ou x11)	Detecção automática via varredura de socket

A maioria dos usuários Linux não precisará definir nenhuma delas. Substitua se a detecção automática falhar (vários compositores, caminho de socket não padrão ou ambientes conteinerizados).

Uso

Lendo sua área de transferência

Copie qualquer coisa (células de planilha, código, texto, uma URL, JSON, uma imagem) e então:

• "Cole minha área de transferência"
• "Leia minha área de transferência"
• "O que está na minha área de transferência?"
• "Copiei alguns dados, dê uma olhada"

Seu assistente chama clipboard_paste e retorna o conteúdo com a estrutura preservada.

Escrevendo na sua área de transferência

Quando seu agente gera um comando, bloco de código ou qualquer texto que você precise usar em outro lugar:

• "Copie isso para minha área de transferência"
• "Coloque esse comando na minha área de transferência"
• "Copie isso como HTML" (escreve text/html para que aplicativos de rich-text colem com formatação)

O agente chama clipboard_copy e o texto limpo vai direto para a área de transferência do sistema. Sem artefatos de renderização de terminal, apenas texto limpo. Isso é especialmente útil com Claude Code (veja acima).

Dica: comportamento de cópia automática. Por padrão, o agente só copia para a área de transferência quando você pede. Se você quiser que comandos e blocos de código sejam copiados automaticamente, adicione isto ao seu prompt de sistema (por exemplo, em um projeto Claude Desktop ou no CLAUDE.md do Claude Code):

Quando você gerar um comando ou bloco de código que o usuário provavelmente colará em outro lugar, copie-o proativamente para a área de transferência usando clipboard_copy.

Formatos de saída de tabela

Quando a área de transferência contém dados tabulares, output_format controla o formato:

Formato	Destino	O que você obtém
markdown	Claude, GitHub, maioria das ferramentas	Tabela de pipe GFM (padrão)
notion	Notion	Tabela de pipe GFM (Notion renderiza essas nativamente)
slack	Slack	cabeçalho *bold* + dados alinhados por espaços em um bloco de código monoespaçado
jira	Jira	marcação wiki ||Header|| / |Cell|
confluence	Confluence	igual a jira (sintaxe wiki compartilhada)
html	E-mail, web, editores de rich-text	<table> com <thead>/<th>/<tbody>/<td>
json	APIs, código	Matriz de objetos chaveados pela linha de cabeçalho
csv	Excel, ferramentas de dados	Valores separados por vírgula

Exemplos:

• "Leia minha área de transferência como Slack" → output_format=slack
• "Converta minha área de transferência em tabela Jira" → output_format=jira
• "Me dê isso como HTML" → output_format=html

Inferência de esquema de tabela

Adicione include_schema=true para obter um resumo dos tipos de coluna junto com a tabela:

"Leia minha área de transferência com esquema"

Tipos inferidos: inteiro, float, moeda, porcentagem, data, booleano, texto. Usa maioria vencedora por coluna — se nenhum tipo representar mais da metade das células não vazias, a coluna é tipada como text. Células vazias são ignoradas; a linha de cabeçalho é excluída da inferência.

Isso é útil ao fornecer dados tabulares ao Claude para instruções SQL CREATE TABLE, mapeamentos Pandas dtype ou regras de validação — Claude obtém os tipos antecipadamente em vez de adivinhar a partir dos dados.

Dicas para acionamento confiável

O servidor inclui instruções MCP que informam ao cliente quando usar as ferramentas de área de transferência, mas os resultados variam por modelo e cliente. Se o agente não captar sua intenção, seja explícito: "copie isso para minha área de transferência" ou "leia o que copiei" funcionam de forma mais confiável.

Se você tiver acesso a um prompt de sistema personalizado (por exemplo, em um projeto Claude Desktop ou em um agente personalizado), pode reforçar o comportamento:

Quando o usuário pedir para copiar a saída, use clipboard_copy para escrevê-la na área de transferência do sistema. Quando o usuário referenciar dados que não estão na conversa, verifique a área de transferência usando clipboard_paste.

Tratamento de conteúdo

Tipo de conteúdo	O que acontece
Tabela de planilha	Analisada de HTML/TSV, retornada no formato de sua escolha (Markdown, JSON, CSV, Slack, Jira, HTML, Notion)
JSON	Impressa de forma organizada em um bloco de código JSON
Código	Retornado em um bloco de código cercado
URL	Retornado limpo como uma URL
HTML rico (sem tabela)	Tags HTML removidas, texto legível retornado
RTF	Retornado em um bloco de código cercado (macOS, Windows e Wayland/X11 via pass-through)
Texto simples	Retornado como está
Imagens (PNG, etc.)	Retornadas como um bloco de conteúdo de imagem MCP que o modelo pode ver e analisar
SVG	Legível como texto via clipboard_read_raw com image/svg+xml, ou retornado como imagem via clipboard_paste. Gravável via clipboard_copy(mime_type="image/svg+xml") — aplicativos que consomem SVG (Inkscape, Figma, navegadores) obtêm a imagem. No Wayland, wl-copy automaticamente também anuncia text/plain, então editores obtêm o código-fonte gratuitamente. No X11 / macOS / Windows, o caminho somente SVG é de MIME único — aplicativos que não suportam SVG não verão nenhum fallback de texto até que a gravação simultânea de múltiplos formatos seja implementada (#109).
Áudio / vídeo	Não suportado; retorna uma mensagem identificando o formato

Como Funciona

1. Detecção de plataforma: Na inicialização, o servidor detecta seu backend de área de transferência (Wayland, X11, macOS ou Windows) e seleciona os comandos de sistema apropriados.
2. Leitura (clipboard_paste): Chama o comando de leitura da área de transferência da plataforma. Tenta text/html primeiro (Google Sheets e Excel colocam marcação <table> na área de transferência), analisa com o html.parser embutido do Python. Recorre a valores separados por tabulação text/plain, depois text/rtf, e então verifica se há imagens.
3. Escrita de texto (clipboard_copy): Envia texto para o comando de escrita da área de transferência da plataforma (wl-copy, xclip -selection clipboard, pbcopy ou PowerShell Set-Clipboard). Suporta um parâmetro mime_type para escrever conteúdo tipado (por exemplo, text/html, text/rtf, image/svg+xml).
4. Escrita de imagens (clipboard_copy_image): Decodifica bytes base64 de PNG ou JPEG e os escreve na área de transferência da plataforma via wl-copy --type, xclip -target, NSPasteboard setData:forType: (macOS) ou Clipboard::SetImage (Windows). Os bytes mágicos são validados contra o tipo MIME declarado antes de qualquer subprocesso ser executado.
5. Passagem de imagem na leitura: Se a área de transferência contém uma imagem (PNG, etc.), ela é retornada como um bloco de conteúdo de imagem MCP codificado em base64 que o modelo pode ver e analisar.
6. Classificação de conteúdo: Conteúdo de texto não tabular é classificado como JSON, URL, código ou texto simples e retornado com formatação apropriada (JSON organizado, blocos de código cercados, etc.).

Limitações

• Áudio e vídeo não são suportados. Se a área de transferência contém áudio ou vídeo, o servidor informa o formato, mas não pode retornar o conteúdo.
• A escrita de imagens suporta apenas PNG e JPEG via clipboard_copy_image. Passagem direta, sem re-codificação. Outros formatos binários (GIF, WebP, TIFF, BMP) ainda não são graváveis. SVG usa o caminho de texto tipado via clipboard_copy(mime_type="image/svg+xml"), pois SVG é XML.
• Escrever múltiplos tipos MIME atomicamente não é suportado no Wayland/X11. wl-copy e xclip carregam um único MIME por invocação, então clipboard_copy_markdown escreve apenas text/html nessas plataformas. No Wayland, wl-copy anuncia automaticamente text/plain para conteúdo UTF-8, mas os bytes retornados são a marcação HTML renderizada (não o código-fonte Markdown) — usuários de vim que colarem após a execução da ferramenta verão <h1>... etc. No X11, alvos de texto simples veem uma área de transferência vazia. Para uma colagem de texto simples do código-fonte Markdown, chame clipboard_copy(markdown_source) diretamente. macOS e Windows suportam gravação atômica de múltiplos formatos via NSPasteboard / DataObject.
• O conteúdo de texto é truncado em 50KB para evitar sobrecarregar a janela de contexto do modelo.
• A cobertura de plataforma é desigual. Linux com Wayland é testado e usado ativamente. Windows foi exercitado de ponta a ponta em um convidado Windows QEMU a partir da v2.5.x (o que revelou e resolveu um bug de codificação UTF-8 no stdin específico do Windows, #129). As implementações X11 e macOS estão completas e têm testes unitários, mas não foram verificadas além disso. Relatórios de bugs e PRs são bem-vindos, especialmente para X11 e macOS.

Desenvolvimento

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run the server directly (stdio mode)
uv run mcp-clipboard

# Run with debug logging
uv run mcp-clipboard --debug

# Test with MCP Inspector
uv run mcp dev src/mcp_clipboard/server.py

O registro de depuração também pode ser habilitado via MCP_CLIPBOARD_DEBUG=1, o que é útil quando o servidor é iniciado pelo Claude Desktop ou Claude Code.

Estrutura do projeto

mcp-clipboard/
├── src/mcp_clipboard/
│   ├── __init__.py          # Package version
│   ├── server.py            # MCP server, tool definitions, debug logging
│   ├── clipboard.py         # Platform-agnostic clipboard backend
│   ├── parser.py            # HTML table parser, formatters, content detection
│   ├── instructions/        # Tool and server descriptions (loaded at startup)
│   │   ├── server.md
│   │   ├── clipboard_copy.md
│   │   ├── clipboard_copy_image.md
│   │   ├── clipboard_copy_markdown.md
│   │   ├── clipboard_paste.md
│   │   ├── clipboard_read_raw.md
│   │   ├── clipboard_list_formats.md
│   │   └── clipboard_version.md
│   └── icons/               # SVG icons for MCP client display (light/dark)
│       ├── mcp-clipboard-logo-light.svg
│       └── mcp-clipboard-logo-dark.svg
├── tests/
│   ├── test_parser.py       # Parser and formatter tests
│   └── test_server.py       # Server, backend, and Wayland detection tests
├── .github/
│   ├── workflows/
│   │   ├── publish.yml      # PyPI publish on v* tags (OIDC trusted publisher)
│   │   └── test-publish.yml # TestPyPI publish on test-v* tags
│   └── ISSUE_TEMPLATE/      # Bug report, feature request, platform test forms
├── pyproject.toml
├── CHANGELOG.md
├── CLAUDE.md                # Claude Code project guidance
├── LICENSE                  # Apache 2.0
└── README.md

Agradecimentos

Este projeto foi projetado e construído em colaboração com Claude Code (CLI da Anthropic para Claude). Arquitetura, decisões de design e gerenciamento de lançamentos foram conduzidos pelo humano; implementação, testes, revisão de código e documentação foram delegados de forma conversacional, com Claude escrevendo código, detectando documentação desatualizada e preenchendo lacunas de cobertura de testes em cada commit.

Licença

Apache 2.0. Veja LICENSE.

© 2026 Chris Means