clipboard-mcp

Servidor MCP que lee y escribe en el portapapeles del sistema: tablas, texto, código, JSON, URLs, imágenes y más. Preserva la estructura de hojas de cálculo (filas/columnas) que se pierde al pegar directamente en Claude. Claude también puede escribir resultados de vuelta en tu portapapeles.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-clipboard

Un servidor MCP que le da a tu asistente de IA acceso directo al portapapeles de tu sistema: lee lo que copiaste o escribe texto limpio directamente en él. Funciona con cualquier cliente compatible con MCP, incluidos Claude Code, Claude Desktop, Cursor, Windsurf y otros.

Por qué existe esto

Pegar pierde la estructura

Cuando copias celdas de Google Sheets o Excel y las pegas en un campo de chat, la estructura tabular (filas y columnas) se destruye. Llega como una cadena plana sin delimitadores. El modelo tiene que adivinar dónde termina una celda y comienza la siguiente, y a menudo se equivoca.

mcp-clipboard lo preserva. En lugar de pegar, dile a tu asistente que "lea mi portapapeles". El servidor lee el portapapeles directamente, detecta datos tabulares del HTML que las aplicaciones de hojas de cálculo colocan en el portapapeles y los devuelve como una tabla Markdown, JSON o CSV correctamente formateada. Sin pérdida de estructura, sin adivinanzas.

Bonus: también corrige copiar desde Claude Code

El renderizador de terminal de Claude Code agrega relleno de 2 caracteres, saltos de línea forzados a ~80 columnas y espacios en blanco finales a toda la salida. Cuando seleccionas y copias texto desde la terminal, esos artefactos vienen incluidos:

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

Esto se ha reportado repetidamente en el repositorio de claude-code (issues #4686, #6827, #7670, #13378, #15199, #25040, #25427, #26016) con docenas de votos positivos y sin corrección publicada.

mcp-clipboard evita el problema por completo. En lugar de copiar texto desde la terminal, pídele a Claude Code que lo coloque en tu portapapeles:

"Copia ese comando a mi portapapeles"

Claude Code llama a clipboard_copy, escribe el texto limpio directamente en tu portapapeles del sistema y lo pegas donde lo necesites. Sin relleno, sin saltos forzados, sin limpieza.

Consejo: Para hacer esto automático, agrega una línea a tu CLAUDE.md de proyecto o global:

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

Claude Code copiará entonces cada comando que sugiera sin que tengas que pedirlo.

Bonus: lee tu selección X11/Wayland sin Ctrl-C

Los escritorios Linux tienen dos portapapeles: el CLIPBOARD que usa Ctrl-C / Ctrl-V, y la selección PRIMARY. PRIMARY es cualquier texto que tengas resaltado actualmente, pegado con clic central. Se actualiza tan pronto como seleccionas algo; no tienes que copiarlo.

mcp-clipboard también lee PRIMARY. Pasa selection="primary" a clipboard_paste, clipboard_read_raw o clipboard_list_formats y el servidor lee el búfer de selección en lugar del portapapeles de Ctrl-C. Algunos flujos de trabajo que esto permite:

Triaje en terminal. Un mensaje de error pasa de largo, selecciónalo con el ratón, pregúntale al modelo qué significa. Tu búfer de Ctrl-C permanece intacto para lo que tuvieras en él.
Selección visual en vim / IDE. Selecciona una función con v, pídele al modelo que la explique o la refactorice.
Lectura en navegador / PDF. Selecciona un párrafo arrastrando, pregunta "¿qué dice esto?" sin salir del flujo de lectura.
Flujos de dos búferes. Mantén un fragmento en CLIPBOARD (Ctrl-C) y extrae uno diferente a través de PRIMARY en la misma conversación.

Solo Linux. macOS y Windows no tienen un búfer equivalente; pasar selection="primary" en esas plataformas devuelve un error claro.

Herramientas

Herramienta	Descripción
`clipboard_paste`	Herramienta principal. Lee cualquier contenido del portapapeles: tablas, texto, código, JSON, URLs, imágenes. Las tablas se formatean como Markdown/JSON/CSV; pasa `include_schema=true` para añadir tipos de columna inferidos. Las imágenes se devuelven como contenido de imagen que el modelo puede ver. El `selection="primary"` opcional lee la selección PRIMARY de X11/Wayland (búfer de clic central / seleccionar-texto-para-pegar) en lugar del portapapeles de Ctrl-C predeterminado.
`clipboard_copy`	Escribe contenido de texto en el portapapeles del sistema. Acepta un parámetro `mime_type` opcional (`text/plain` por defecto; también `text/html`, `text/rtf`, `image/svg+xml` o cualquier `text/*` en Wayland/X11).
`clipboard_copy_markdown`	Renderiza markdown a HTML y coloca ambos formatos en el portapapeles para que los destinos de pegado elijan el correcto: Slack/Gmail/Notion/Discord obtienen texto enriquecido; vim/terminal obtienen la fuente. macOS/Windows escriben ambos atómicamente; Wayland/X11 son de un solo MIME y escriben solo `text/html`.
`clipboard_copy_image`	Escribe una imagen PNG o JPEG en el portapapeles del sistema desde bytes codificados en base64. Paso directo sin recodificación; los bytes mágicos se validan contra el MIME declarado. Usa `clipboard_copy` para texto.
`clipboard_list_formats`	Lista qué tipos MIME están actualmente en el portapapeles. Acepta `selection="primary"` para la selección PRIMARY de X11/Wayland.
`clipboard_read_raw`	Devuelve el contenido bruto del portapapeles para un tipo MIME dado (diagnóstico). Cualquier tipo no binario pasa; solo se rechazan `image/`, `audio/`, `video/*` y `application/octet-stream`. Usa `clipboard_paste` para imágenes. Acepta `selection="primary"` para la selección PRIMARY de X11/Wayland.
`clipboard_version`	Devuelve la versión del paquete mcp-clipboard en ejecución como `{"name": "mcp-clipboard", "version": "<x.y.z>"}`. Diagnóstico. Útil para hosts que no muestran el bloque estándar de MCP `serverInfo` al modelo, y para arneses de prueba que necesitan registrar qué compilación sirvió una ejecución determinada.

Configuración

Paso 1: Instala un ejecutor de paquetes Python

mcp-clipboard es un paquete Python en PyPI. Cualquier herramienta Python que pueda instalar y lanzar puntos de entrada de scripts de consola funciona para ejecutarlo como servidor MCP. Las dos opciones más comunes son pipx y uv; ambas aparecen en las insignias de conteo de instalaciones en la parte superior de este README y ambas están en uso activo. Elige la que tengas o prefieras:

pipx: las instrucciones de instalación por plataforma están en los documentos oficiales de instalación de pipx. En la mayoría de las distribuciones, pipx está disponible a través del gestor de paquetes del sistema (apt, dnf, pacman, brew, etc.).
uv: las instrucciones de instalación por plataforma están en los documentos oficiales de instalación de uv. Astral documenta rutas de gestores de paquetes, descargas de binarios independientes firmados e instaladores de shell para cada plataforma.

Verifica que tu ejecutor elegido esté en PATH:

pipx --version   # if you chose pipx

uv --version     # if you chose uv

El resto de esta sección muestra comandos para ambos ejecutores; sustituye el que hayas instalado.

Paso 2: Instala la herramienta de portapapeles de la plataforma (solo Linux)

macOS y Windows tienen todo lo necesario integrado. Linux necesita una utilidad CLI:

Plataforma	Herramienta	Instalación
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` o `sudo apt install xclip`
macOS	Integrado	No se necesita instalación (`pbcopy` / `pbpaste`)
Windows	Integrado	No se necesita instalación (PowerShell)

Estado de la plataforma: Linux con Wayland está probado y en uso activo. Windows se ha ejercitado de extremo a extremo en un invitado Windows de QEMU (un error real de codificación específico de Windows, #129, se encontró y corrigió mediante esas pruebas en v2.5.x). Las implementaciones de X11 y macOS están completas pero no verificadas más allá de las pruebas unitarias. Se aceptan informes de errores y PRs.

Paso 3: Verifica que mcp-clipboard funciona en tu sistema

Antes de conectarlo a un cliente, confirma que el paquete se instala y detecta tu plataforma correctamente. Con pipx:

pipx run mcp-clipboard --check

O con uv:

uvx mcp-clipboard --check

Ambas formas obtienen el paquete bajo demanda sin una instalación permanente (usa pipx install mcp-clipboard o uv tool install mcp-clipboard primero si prefieres instalarlo de forma persistente). Salida esperada:

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

Si ves Backend: NOT AVAILABLE, sigue la pista específica de la plataforma en el mensaje de error (típicamente: instala la herramienta de portapapeles de Linux del Paso 2) y vuelve a ejecutar.

Paso 4: Registra el servidor con tu cliente MCP

El host MCP lanza mcp-clipboard mediante un par command + args. Tanto pipx como uv exponen un subcomando de ejecución única que obtiene y ejecuta el paquete, por lo que las configuraciones más convenientes usan esas formas.

Claude Code

Con pipx:

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

Con uv:

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

Claude Desktop

Localiza tu archivo de configuración de Claude Desktop (pega la ruta en la barra de direcciones de tu gestor de archivos para saltar directamente allí):

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

Agrega una entrada a mcpServers usando una de las formas siguientes. Con pipx:

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

O con uv:

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

Guarda el archivo y luego cierra y relanza completamente Claude Desktop para que se cargue el nuevo servidor.

Consejo para Windows: Claude Desktop almacena en caché el entorno (incluido PATH) desde el momento en que se lanza. Si pipx/uvx se instaló después de que se iniciara Claude Desktop, Claude Desktop no lo verá hasta que se reinicie. Si el fragmento anterior produce "Server failed to start" o un error de estilo "command not found" en los registros de MCP, haz clic derecho en el icono de la bandeja de Claude Desktop, elige Quit y luego vuelve a abrir Claude Desktop. Un cierre con la X de la barra de tareas solo oculta la ventana; el entorno en caché sigue allí.

Otros clientes MCP

Cualquier cliente que admita servidores MCP stdio puede usar mcp-clipboard. Las formas comunes de ejecución única son pipx run mcp-clipboard y uvx mcp-clipboard; si has instalado mcp-clipboard de forma persistente (pipx install mcp-clipboard o uv tool install mcp-clipboard), el binario mcp-clipboard resultante en PATH también funciona como command. Consulta la documentación de tu cliente sobre cómo registrar servidores MCP.

Paso 5: Confirma que funciona de extremo a extremo

En tu cliente, pregunta:

¿Qué hay en mi portapapeles?

El cliente debería llamar a clipboard_paste y devolver el contenido. Si copiaste una selección de hoja de cálculo o una URL de antemano, la verás formateada adecuadamente.

Si no sucede nada u obtienes un error de herramienta, vuelve a ejecutar --check (el ejecutor que usaste en el Paso 3) para confirmar que la instalación del paquete está sana, y luego revisa los registros del servidor MCP de tu cliente (cada host MCP los expone de manera diferente; consulta la documentación de tu cliente).

Instalación desde el código fuente

Si prefieres un clon local en lugar de instalar desde PyPI:

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

Luego apunta tu cliente a la instalación local:

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

Variables de entorno

Las variables de entorno se pueden pasar mediante la clave "env" en la configuración.

Variable	Plataforma	Propósito	Predeterminado
`MCP_CLIPBOARD_DEBUG`	Todas	Habilitar registro de depuración (`1` para habilitar)	Desactivado
`WAYLAND_DISPLAY`	Linux (Wayland)	Nombre del socket del compositor o ruta absoluta	Auto-detectado
`XDG_RUNTIME_DIR`	Linux (Wayland)	Directorio que contiene el socket de Wayland	`/run/user/<uid>`
`XDG_SESSION_TYPE`	Linux	Sugerencia de tipo de sesión (`wayland` o `x11`)	Auto-detectado mediante escaneo de sockets

La mayoría de los usuarios de Linux no necesitarán configurar ninguna de estas. Anula si la auto-detección falla (múltiples compositores, ruta de socket no estándar o entornos contenedorizados).

Uso

Leer tu portapapeles

Copia cualquier cosa (celdas de hoja de cálculo, código, texto, una URL, JSON, una imagen) y luego:

"Pega mi portapapeles"
"Lee mi portapapeles"
"¿Qué hay en mi portapapeles?"
"Copié algunos datos, échales un vistazo"

Tu asistente llama a clipboard_paste y devuelve el contenido con la estructura preservada.

Escribir en tu portapapeles

Cuando tu agente genera un comando, bloque de código o cualquier texto que necesites usar en otro lugar:

"Copia eso en mi portapapeles"
"Pon ese comando en mi portapapeles"
"Copia eso como HTML" (escribe text/html para que las aplicaciones de texto enriquecido peguen con formato)

El agente llama a clipboard_copy y el texto limpio va directamente a tu portapapeles del sistema. Sin artefactos de renderizado de terminal, solo texto limpio. Esto es especialmente útil con Claude Code (ver arriba).

Consejo: comportamiento de copiado automático. Por defecto, el agente solo copia al portapapeles cuando se lo pides. Si quieres que los comandos y bloques de código se copien automáticamente, añade esto a tu prompt de sistema (por ejemplo, en un proyecto de Claude Desktop o en el CLAUDE.md de Claude Code):

Cuando generes un comando o bloque de código que el usuario probablemente pegará en otro lugar, cópialo proactivamente al portapapeles usando clipboard_copy.

Formatos de salida de tablas

Cuando el portapapeles contiene datos tabulares, output_format controla el formato:

Formato	Destino	Lo que obtienes
`markdown`	Claude, GitHub, la mayoría de herramientas	Tabla de tuberías GFM (predeterminado)
`notion`	Notion	Tabla de tuberías GFM (Notion las renderiza de forma nativa)
`slack`	Slack	Encabezado `bold` + datos alineados con espacios en un bloque de código monoespaciado
`jira`	Jira	Marcado wiki `\|\|Header\|\|` / `\|Cell\|`
`confluence`	Confluence	Igual que `jira` (sintaxis wiki compartida)
`html`	Correo, web, editores de texto enriquecido	`<table>` con `<thead>`/`<th>`/`<tbody>`/`<td>`
`json`	APIs, código	Matriz de objetos clave-valor por fila de encabezado
`csv`	Excel, herramientas de datos	Valores separados por comas

Ejemplos:

"Lee mi portapapeles como Slack" → output_format=slack
"Convierte mi portapapeles a tabla de Jira" → output_format=jira
"Dame eso como HTML" → output_format=html

Inferencia de esquema de tablas

Añade include_schema=true para obtener un resumen de tipos de columna junto con la tabla:

"Lee mi portapapeles con esquema"

Tipos inferidos: entero, flotante, moneda, porcentaje, fecha, booleano, texto. Usa mayoría por columna: si ningún tipo representa más de la mitad de las celdas no vacías, la columna se tipifica como text. Las celdas vacías se omiten; la fila de encabezado se excluye de la inferencia.

Esto es útil al pasar datos tabulares a Claude para sentencias SQL CREATE TABLE, mapeos de Pandas dtype o reglas de validación: Claude obtiene los tipos de antemano en lugar de adivinarlos a partir de los datos.

Consejos para una activación fiable

El servidor incluye instrucciones MCP que indican al cliente cuándo usar las herramientas de portapapeles, pero los resultados varían según el modelo y el cliente. Si el agente no capta tu intención, sé explícito: "copia eso en mi portapapeles" o "lee lo que copié" funcionan de manera más fiable.

Si tienes acceso a un prompt de sistema personalizado (por ejemplo, en un proyecto de Claude Desktop o un agente personalizado), puedes reforzar el comportamiento:

Cuando el usuario pida copiar una salida, usa clipboard_copy para escribirla en el portapapeles del sistema. Cuando el usuario haga referencia a datos que no están en la conversación, revisa el portapapeles usando clipboard_paste.

Manejo de contenido

Tipo de contenido	Qué sucede
Tabla de hoja de cálculo	Se analiza desde HTML/TSV y se devuelve en el formato que elijas (Markdown, JSON, CSV, Slack, Jira, HTML, Notion)
JSON	Formateado de forma legible en un bloque de código JSON
Código	Se devuelve en un bloque de código delimitado
URL	Se devuelve limpiamente como URL
HTML enriquecido (sin tabla)	Se eliminan las etiquetas HTML y se devuelve texto legible
RTF	Se devuelve en un bloque de código delimitado (macOS, Windows y Wayland/X11 mediante pass-through)
Texto plano	Se devuelve tal cual
Imágenes (PNG, etc.)	Se devuelven como un bloque de contenido de imagen MCP que el modelo puede ver y analizar
SVG	Legible como texto mediante `clipboard_read_raw` con `image/svg+xml`, o devuelto como imagen mediante `clipboard_paste`. Escribible mediante `clipboard_copy(mime_type="image/svg+xml")`: las aplicaciones que consumen SVG (Inkscape, Figma, navegadores) reciben la imagen. En Wayland, `wl-copy` también anuncia automáticamente `text/plain`, por lo que los editores obtienen el código fuente gratis. En X11 / macOS / Windows, la ruta solo-SVG es de MIME único: las aplicaciones que no reconocen SVG no verán ningún respaldo de texto hasta que se implemente la escritura simultánea multi-formato (#109).
Audio / video	No compatible; devuelve un mensaje que identifica el formato

Cómo funciona

Detección de plataforma: Al iniciar, el servidor detecta tu backend de portapapeles (Wayland, X11, macOS o Windows) y selecciona los comandos de sistema adecuados.
Lectura (clipboard_paste): Llama al comando de lectura de portapapeles de la plataforma. Prueba text/html primero (Google Sheets y Excel colocan marcado <table> en el portapapeles), analiza con el html.parser integrado de Python. Recurre a valores separados por tabulaciones text/plain, luego a text/rtf, y después verifica si hay imágenes.
Escritura de texto (clipboard_copy): Envía texto al comando de escritura de portapapeles de la plataforma (wl-copy, xclip -selection clipboard, pbcopy o PowerShell Set-Clipboard). Admite un parámetro mime_type para escribir contenido tipificado (por ejemplo, text/html, text/rtf, image/svg+xml).
Escritura de imágenes (clipboard_copy_image): Decodifica bytes base64 de PNG o JPEG y los escribe en el portapapeles de la plataforma mediante wl-copy --type, xclip -target, NSPasteboard setData:forType: (macOS) o Clipboard::SetImage (Windows). Los bytes mágicos se validan contra el tipo MIME declarado antes de que se ejecute cualquier subproceso.
Pass-through de imágenes en lectura: Si el portapapeles contiene una imagen (PNG, etc.), se devuelve como un bloque de contenido de imagen MCP codificado en base64 que el modelo puede ver y analizar.
Clasificación de contenido: El contenido de texto no tabular se clasifica como JSON, URL, código o texto plano y se devuelve con el formato adecuado (JSON formateado, bloques de código delimitados, etc.).

Limitaciones

Audio y video no son compatibles. Si el portapapeles contiene audio o video, el servidor informa el formato pero no puede devolver el contenido.
La escritura de imágenes admite solo PNG y JPEG mediante clipboard_copy_image. Pass-through, sin recodificación. Otros formatos binarios (GIF, WebP, TIFF, BMP) aún no se pueden escribir. SVG usa la ruta de texto tipificado mediante clipboard_copy(mime_type="image/svg+xml") ya que SVG es XML.
La escritura atómica de múltiples tipos MIME no es compatible en Wayland/X11. wl-copy y xclip llevan un solo MIME por invocación, por lo que clipboard_copy_markdown escribe solo text/html en esas plataformas. En Wayland, wl-copy anuncia automáticamente text/plain para contenido UTF-8, pero los bytes devueltos son el marcado HTML renderizado (no el código fuente de markdown): los usuarios de vim que peguen después de que la herramienta se ejecute verán <h1>..., etc. En X11, los destinos de texto plano ven un portapapeles vacío. Para un pegado en texto plano del código fuente de markdown, llama a clipboard_copy(markdown_source) directamente. macOS y Windows sí admiten escrituras atómicas multi-formato mediante NSPasteboard / DataObject.
El contenido de texto se trunca a 50KB para evitar abrumar la ventana de contexto del modelo.
La cobertura de plataformas es desigual. Linux con Wayland está probado y se usa activamente. Windows se ha ejercitado de extremo a extremo en un invitado Windows QEMU a partir de v2.5.x (lo que reveló y resolvió un error de codificación UTF-8 de stdin solo en Windows, #129). Las implementaciones de X11 y macOS están completas y tienen pruebas unitarias, pero no se han verificado más allá. Los informes de errores y las solicitudes de extracción son bienvenidos, especialmente para X11 y macOS.

Desarrollo

# 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

El registro de depuración también se puede habilitar mediante MCP_CLIPBOARD_DEBUG=1, lo cual es útil cuando el servidor es lanzado por Claude Desktop o Claude Code.

Estructura del proyecto

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

Agradecimientos

Este proyecto fue diseñado y construido en colaboración con Claude Code (la CLI de Anthropic para Claude). La arquitectura, las decisiones de diseño y la gestión de versiones fueron impulsadas por el humano; la implementación, las pruebas, la revisión de código y la documentación se delegaron de forma conversacional, con Claude escribiendo código, detectando documentación desactualizada y cubriendo brechas de cobertura de pruebas en cada commit.

Licencia

Apache 2.0. Ver LICENCIA.