Cómo usar Penpot MCP con Claude Code, Cursor y OpenCode

Lo que empezó como una herramienta de diseño open source para plantar cara a Figma ahora habla directo con tu agente de IA. Y eso cambia bastante las reglas del juego.

Te lo cuento porque vengo defendiendo Penpot desde hace años como la alternativa libre para equipos de diseño. Lo dije cuando probé Claude Design y me quedé con ganas de un equivalente abierto: Penpot ya tiene su propia vía para enchufar un agente a tus ficheros sin atarte a ningún ecosistema cerrado. Se llama Penpot MCP y es gratis.

Esto es lo que vamos a ver hoy con las manos en el teclado:

• Qué es un flujo de IA en Penpot y por qué no es magia, es coincidencia de patrones.
• Cómo el servidor MCP conecta tus ficheros de diseño con cualquier agente y cualquier modelo.
• La configuración en remoto paso a paso, sin escribir una línea de código.
• Los tres caminos que abre: de diseño a código, de código a diseño y de diseño a documentación.
• Los límites que nadie te cuenta en los vídeos de demo.

Qué es un flujo de IA en Penpot ¶

Un flujo de IA es un proceso repetible donde defines un objetivo, unas restricciones y unos puntos de control, y luego usas un agente para planificar, editar, auditar o automatizar tareas. Empieza con un prompt y termina con diseño, código o incluso documentación como resultado.

Hasta aquí suena a folleto. Vamos a lo concreto.

Si le pides a un modelo “créame una serie de mockups para un checkout de ecommerce”, lo más probable es que te escupa algo visualmente apañado pero genérico. Bonito de un vistazo, lleno de incoherencias en cuanto rascas un poco, y sin ninguna relación con lo que necesitas para tu producto real.

¿Por qué pasa esto? Porque los modelos de lenguaje se entrenan con la web y otros medios. Sin contexto adicional, el modelo coge la media de lo que aparece con más frecuencia y aproxima lo que encaja con tu petición. Eso explica por qué tanta salida de IA acaba pareciéndose a Tailwind o a un dashboard de Shadcn: es lo que más abunda ahí fuera.

🔑 No hablamos de magia, hablamos de coincidencia de patrones. La calidad del resultado depende del contexto que le des, y ahí es donde MCP marca la diferencia frente a un generador a ciegas.

Aquí entra Penpot. En lugar de que el agente se invente el universo, MCP le da acceso al contexto real de tu fichero: tus componentes, tus tokens, tu jerarquía, tus nombres. El modelo deja de adivinar y empieza a trabajar sobre lo que ya tienes montado.

Fíjate en la captura: hay un boceto a mano seleccionado en el lienzo y un prompt que le dice al agente que mire la librería del fichero y los assets para crear una splash screen siguiendo la misma estructura, estilo visual y tamaño que el resto de boards. Eso es un flujo de IA en estado puro: parte de tu material real, no de la nada.

El contexto importa porque la IA ya está dentro de tu trabajo diario. Según el JetBrains Developer Ecosystem 2025, el 85% de los desarrolladores ya usa IA con regularidad y el 62% depende de al menos un asistente de código. La pregunta dejó de ser si la usas y pasó a ser con cuánto contexto la usas.

Curso gratis · paso a paso

Ese 'objetivo, restricciones y control' que define un flujo de IA tiene método

Te llevas el ciclo completo de Spec Driven Development con OpenSpec sobre un proyecto real y en modo asistido: el mismo principio de definir objetivo y restricciones antes de soltar al agente, llevado a método para que deje de improvisar.

Entra en el curso gratis →

Cómo conecta Penpot MCP tu diseño con los agentes ¶

MCP son las siglas de Model Context Protocol, el estándar abierto que Anthropic publicó en noviembre de 2024. Si quieres el repaso completo del protocolo y de sus primos (ACP, A2A, Agent Skills), lo tienes en esta guía de protocolos de la IA. Y si lo que buscas es configurarlo en tu agente favorito, ya escribí cómo instalar MCP en 16 agentes.

Para Penpot quédate con la analogía de siempre: MCP es el USB-C que conecta tu agente con tus ficheros de diseño. La adopción del protocolo no es un experimento de laboratorio: hablamos de más de 97 millones de descargas mensuales de sus SDKs y más de 10.000 servidores activos.

Hay tres piezas que tienen que entenderse entre sí, y conviene no confundirlas:

1. El servidor MCP: un servicio que expone herramientas a tu cliente de IA. Recibe las peticiones del cliente y las reenvía a Penpot.
2. El plugin MCP dentro de Penpot: un plugin que se ejecuta en Penpot y conecta tu fichero abierto con el servidor. Es lo que permite al servidor acceder a la página que tienes en foco.
3. El cliente MCP: la herramienta donde escribes los prompts. Cursor, Claude Code, OpenCode o cualquier cliente compatible.

Lo interesante es que Penpot MCP está construido sobre la Plugin API de Penpot, esa misma API pública que el equipo lleva años puliendo. El servidor traduce tu lenguaje natural en código que aprovecha la API del plugin, y por eso puede leer y modificar elementos reales en el lienzo.

💡 En Penpot el diseño se expresa como código (SVG y estructura de datos abierta). Para un agente eso es oro: puede leer tu diseño como si fuera un repositorio y operar sobre él con precisión, no a base de píxeles aproximados.

En el centro de esa imagen está la pieza clave: el Penpot MCP Server con las flechas apuntando en las dos direcciones. A la izquierda el agente ejecuta sus herramientas (ahí se ve un export_shape y su razonamiento), y a la derecha el boceto de antes ya es una pantalla terminada. Ese ir y venir es lo que convierte a Penpot MCP en algo más que un generador de un solo sentido.

Otra ventaja que pesa: es agnóstico. No te casa con un modelo ni con un cliente concreto. Puedes usar Claude, Gemini o GPT, lo que tengas a mano o lo que más te convenga para cada tarea (si dudas cuál, tienes mi comparativa de modelos de IA para programar). Y como cualquier MCP, separa responsabilidades: quien construye el servidor no necesita saber qué modelo lo va a consumir.

Configura Penpot MCP en remoto en cinco pasos ¶

Penpot ofrece dos modos: remoto y local. El remoto está alojado por ellos, no instalas nada en tu máquina y es la vía rápida para la mayoría. El local se ejecuta en tu equipo, da más control y seguridad, y está pensado para quien se maneja con la terminal sin sudores fríos.

Empezamos por el remoto, que es el que te recomiendo para catar esto hoy mismo. No vas a escribir ni una línea de código.

1. Entra en Tu cuenta → Integraciones → MCP Server y activa la función con el interruptor de estado. Penpot recuerda este ajuste por usuario entre sesiones.
2. Si es tu primera vez, te pedirá generar una clave MCP. Cuidado aquí: la clave se muestra una sola vez. Guárdala como si fuera una contraseña, porque eso es exactamente lo que es. Nada de pegarla en capturas ni en logs.
3. En esa misma sección, copia la URL del servidor. Esa URL ya incluye tu clave como userToken, así que trátala con el mismo mimo que la clave.
4. En tu cliente compatible (Cursor, Claude Code y compañía) añade un nuevo servidor apuntando a esa URL.
5. Abre el fichero de Penpot con el que vas a trabajar y comprueba que el plugin MCP está conectado.

Si trabajas en local y usas Claude Code, el alta es un comando y poco más:

# Añade el servidor MCP de Penpot a tu proyecto de Claude Code
claude mcp add penpot -t http http://localhost:4401/mcp

El servidor local levanta por defecto en el puerto 4401 y expone el endpoint moderno /mcp. Hay un detalle que parece tontería pero te ahorra un cabreo: no cierres la ventana del plugin mientras usas MCP, porque al cerrarla se corta la conexión.

⚠️ Algunos navegadores bloquean el acceso a red local por seguridad. En Brave, por ejemplo, tendrás que desactivar el “Shield” para el sitio de Penpot. Si el navegador se niega a conectar con el plugin servido en local, prueba con Firefox.

Un apunte sobre el repositorio, por si vas a fisgar el código: el antiguo repo penpot/penpot-mcp se archivó el 3 de febrero de 2026 y su contenido vive ahora integrado en el repositorio principal de Penpot. No te despistes clonando lo viejo.

El test de “hola mundo” antes de tocar nada ¶

Antes de pedirle al agente que te reorganice medio sistema de diseño, conviene asegurarse de que la cañería no tiene fugas. El equivalente al hello world aquí es ridículo de simple y te ahorra horas de frustración persiguiendo fantasmas.

Pon tu cliente en modo Plan (de solo lectura, no toca tu trabajo) y lanza este prompt:

What is the name of my current open Penpot file?

¿Te responde con el nombre correcto de tu fichero? Pues ya está, la conexión funciona y el agente está viendo lo que tiene que ver. ¿Te suelta una evasiva o un nombre inventado? Entonces hay algo mal en la configuración antes de seguir.

Esta comprobación tan boba tiene su miga. Si el agente acierta el nombre, sabes que el plugin está conectado, que el fichero correcto está en foco y que el servidor está hablando con tu cliente. Tres cosas de golpe con un solo prompt.

🛡️ Empieza siempre en modo Plan. Es de solo lectura, así que el agente puede inspeccionar, listar y exportar, pero no te va a tocar el fichero. Cuando tengas confianza, pasas a modo Build, que es el que ejecuta y edita. Y antes de cualquier cambio gordo: haz copia de seguridad.

Cada domingo comparto con +6.700 developers lo que voy aprendiendo sobre meter IA en el trabajo real: qué merece la pena, qué quema tokens y qué se queda en humo. Gratis desde 2018. Suscríbete a la dinamita →

Los tres caminos: de diseño a código, de código a diseño y de diseño a docs ¶

Aquí es donde Penpot MCP se separa del pelotón. La mayoría de integraciones tiran en una sola dirección. Penpot abre flujos multidireccionales, y eso multiplica los casos de uso.

De diseño a código. El clásico. Tienes una pantalla diseñada en Penpot y le pides al agente que la reconstruya en HTML y CSS, en React o en lo que uses. Como el diseño ya está expresado como código, la traducción sale fiel: navegable, clicable y respetando la maquetación. En las demos del equipo se ve cómo el resultado mantiene el layout sin descuadrarse, justo donde otras herramientas experimentales empiezan a torcer columnas.

De código a diseño. El camino inverso, menos habitual y más sorprendente. Partes de código o de una especificación y generas elementos de diseño dentro de Penpot. Útil cuando el front va por delante del diseño y quieres documentar lo que ya existe.

De diseño a documentación. Le pides al agente que extraiga estructura y significado de tu fichero y te genere documentación o un mapeo entre componentes y código. Esto es especialmente goloso cuando heredas un fichero ajeno: puedes preguntarle al agente qué hay dentro y para qué sirve cada parte, en vez de bucear a mano por las capas.

Y hay una tarea que, por aburrida, se lleva la palma en el día a día: la generación de tokens y variantes. Crear un set de tokens de color a mano es de esas cosas en las que los humanos fallamos por inconsistencia pura. Renombras un token, se te cuela otro fuera de convención, y a la tercera ya no sabes si era primary-500 o brand-accent. El agente, si le das una estructura de nombres clara, hace ese trabajo repetitivo sin pestañear.

Mira el ejemplo de la captura: el prompt pide extender un componente Input existente con nuevas variantes (password, email, select) manteniendo la coherencia con el sistema de diseño actual. Abajo a la derecha, el panel del plugin marca Connected. Eso es exactamente la clase de trabajo repetitivo y propenso a errores que merece la pena delegar, siempre con tu revisión por delante.

Si quieres profundizar en darle reglas de marca al agente con un fichero plano, te conté cómo funciona DESIGN.md para crear diseños con IA basados en reglas. La filosofía es la misma: cuanto mejor defines el terreno, mejor juega la IA.

Cómo escribir prompts que no quemen tokens ¶

Aquí va la verdad incómoda: el mayor error no es técnico, es de comunicación. La gente le habla al agente como si fuera un compañero de mesa. Le suelta “hazme un formulario de registro” y espera que lo entienda como lo entendería un colega con tres años de contexto del proyecto.

No funciona así. Y cada palabra de más, cada repetición y cada instrucción contradictoria consume tokens y, a veces, empeora el resultado.

Un token es la unidad de trabajo del modelo, viene a equivaler a un carácter de texto, y la mayoría de proveedores te cobran por él. Además, los tokens se correlacionan con el esfuerzo de cómputo y, por tanto, con el gasto energético. Traducido: prompts más limpios significan menos factura y menos consumo. Una de las diseñadoras de Penpot contó que se fundió 10 dólares en tokens construyendo un sistema con un prompt demasiado verboso. No es una anécdota aislada.

Estas son las prácticas que el equipo de Penpot recomienda, y que coinciden con lo que veo funcionar a diario:

1. Dale un rol antes que una tarea. No vale “actúa como diseñador UX/UI”, es demasiado vago. Escríbele una mini descripción de puesto: “Eres un diseñador de producto senior, experto en sistemas de diseño y accesibilidad WCAG. Entiendes cómo Penpot trabaja con código y no tomas decisiones de negocio sin datos.”
2. Estructura el prompt como un brief, no como una conversación. Define el problema, las restricciones y qué significa “terminado”. Esquemas y reglas, no prosa inspiradora.
3. Pide transformaciones, no resultados finales. Como a un niño no le dices “deja la habitación impecable” sino “recoge la ropa, ordena los juguetes, barre”, al agente lo guías por fases: ajusta la jerarquía visual, reduce el ruido eliminando bordes innecesarios, normaliza el espaciado con nuestros tokens.
4. Dile qué NO hacer. Tan explícito como lo que sí: no inventes colores nuevos, no añadas patrones de navegación, no toques la identidad visual.
5. Itera, no lo resuelvas de una. El prompt perfecto de un solo disparo no existe. La primera salida casi nunca es la final, y eso forma parte del flujo.

💡 Si solo te llevas una idea de esta sección: trata el prompt como un contrato estructurado, no como un diario donde le cuentas tu vida al modelo. Menos ruido, más estructura.

Hay un matiz sobre el modelo que conviene tener claro. Para tareas con razonamiento multi-paso o traducción de diseño a código, el modelo que elijas impacta de lleno en la calidad. Para tareas repetitivas y bien definidas, un modelo más sencillo cumple. Los modelos fuertes en flujos agénticos con MCP marcan la diferencia justo en este tipo de trabajo.

Dónde Penpot MCP brilla frente a generadores genéricos ¶

Cuando le pides a Penpot que genere una maquetación nueva, por defecto tira de flex y grid según lo que mejor encaje. Incluso si le pides posicionar un elemento en absoluto, el agente suele inferir que querías un flex layout. No te empuja a maquetaciones estáticas con todo clavado a coordenadas, te empuja hacia buenas prácticas.

Eso sí: si necesitas diseño responsive, el truco está en diseñar tú los breakpoints en Penpot, como si fueran media queries. Cuanto más contexto visual le das (un board por cada breakpoint), mejor representa el diseño fluido y adaptado. Es la versión moderna de esa documentación de handoff que los diseñadores llevamos años preparando.

Otra cosa que sorprende: el MCP puede leer y usar de varias librerías conectadas a tu equipo. Si tienes el sistema de diseño partido en dos o tres librerías, o un set de iconos aparte, el agente puede recorrerlas todas. Esto convierte al MCP en una herramienta de exploración: abres un fichero compartido por alguien del equipo y le preguntas por su estructura sin tener que rastrearla tú.

Y aquí viene la pulla cariñosa a la competencia. He probado generadores que producen UIs preciosas pero que tienen “sabor”: las miras y sabes que las parió tal o cual modelo, porque la interfaz siempre tiene el mismo aire. Eso está bien si quieres algo que se parezca a todo lo demás. Para trabajo profesional, donde resuelves un problema específico, lo genérico no sirve.

🔑 Penpot MCP no es un botón mágico de “hazme una app”. Es una herramienta profesional para diseño y sistemas de diseño. Si quieres que funcione bien, empieza haciendo trabajo profesional: jerarquía clara, nombres consistentes, componentes reutilizables.

Los límites que nadie te cuenta en las demos ¶

Toda herramienta merece que evalúes su utilidad antes de meterla en cada tarea. Y la IA aplicada al diseño tiene grietas que conviene mirar de frente.

La más importante: necesitas las habilidades para verificar la salida. Los modelos se equivocan con una seguridad pasmosa. La salida es una conjetura basada en sus datos de entrenamiento y en lo que tú le diste. Se inventan funciones que no existen porque sí existen en productos parecidos, se sacan endpoints de la manga porque siguen un patrón estándar, generan tokens de diseño de más porque es lo común. Trata el código generado como un pull request de un junior: léelo, entiéndelo, cuestiónalo y no fusiones lo que no puedas mantener.

El segundo límite es humano. Es tentador usar la IA para saltarte la experiencia de tus compañeros. ¿Para qué un diseñador si el agente te suelta un mockup mono? ¿Para qué un desarrollador si el agente maqueta tu diseño sin rechistar? Pues porque buena parte del trabajo profesional sale de la pericia ganada a base de años, de pelearse con un legacy y de discusiones de ida y vuelta entre gente con criterio. Antes que al modelo, recurre a quien sabe.

El tercero es la repetibilidad. La gracia de un flujo automatizado es que se repite. Pero con IA eso es resbaladizo: cuando montes un flujo que vas a usar varias veces, comprueba que otra persona pueda seguir los mismos pasos y obtener una salida y una calidad parecidas.

Y luego están los de toda la vida con cualquier herramienta de terceros:

• Datos sensibles. Nada de secretos, información personal (PII) ni datos propietarios en tus prompts o contexto. Limita las carpetas y ficheros a los que dejas acceder al modelo.
• Propiedad intelectual. Los modelos se entrenaron raspando media web, así que existe la posibilidad de que la salida infrinja derechos de terceros. Revisa antes de publicar o desplegar.
• Datos de entrenamiento. Tu input puede acabar entrenando al modelo. Lee los términos del cliente y del proveedor.
• Gasto y energía. Los tokens cuestan, y se acumulan rápido. Mira los logs de uso para entender qué tipo de prompts te disparan el consumo.

⚠️ Valida siempre tres cosas que la IA borda con un error tipográfico de un solo carácter: URLs, APIs y estadísticas. Un carácter mal puesto rompe un enlace, tumba un script o cambia el significado de un dato. Y lo peor es que parece real.

Verificar no es opcional

Las habilidades para verificar lo que escupe la IA, en una masterclass

Te llevas métodos prácticos para revisar y verificar lo que generan los agentes: skills, pruebas en navegador con Playwright y adversarial review entre modelos. Justo la pericia que este post te insiste en tener.

Ver el método entero →

Masterclass en directo · adversarial review + casos Gherkin

Por dónde empezar sin pegarte un tiro en el pie ¶

La clave para saber cuándo usar un flujo de IA es entender cuándo la intervención humana vale más. ¿Ahorras tiempo de verdad contando las iteraciones y reprocesos? ¿Reduces esfuerzo sin meter más errores? ¿Tienes sistemas para cazar los fallos del modelo antes de que lleguen a producción?

Si las respuestas te convencen, este es el camino que recomienda el propio equipo de Penpot, y a mí me parece de cabeza fría:

1. Solo lectura primero. “Audita mis tokens de diseño”, sin edición. Pruebas si el flujo es viable.
2. Una edición pequeña y reversible. Por ejemplo, normalizar el espaciado de un solo board. Compruebas cómo de bien ejecuta la tarea.
3. Un objetivo concreto y alcanzable. Iteras para mejorar el flujo y hacerlo más repetible.

Hay una trampa con la que cierro, y es la más sutil. Es tentador eliminar todo el “trabajo aburrido”. Pero muchas veces ese trabajo es justo donde aparecen las mejores iteraciones: te das cuenta de que la estructura de nombres no funciona, o de que el flujo interactivo se salta un paso clave. Diseñar no es dibujar rectángulos y programar no es teclear ficheros. Cuidado con automatizar la parte valiosa del proceso.

Los flujos de IA no son un atajo para saltarte la habilidad de diseñar y desarrollar. Son una forma de ir más rápido en las partes que puedes verificar, para dedicar tu atención a las decisiones que solo tu equipo debería tomar.

Yo venía pidiendo un equivalente abierto a las herramientas de diseño con IA cerradas. Resulta que llevaba meses creciendo al lado, en una herramienta que ya conocía. ¿Qué te impide a ti probarlo este finde?

TL;DR ¶

• 🚀 Penpot MCP conecta tus ficheros de diseño open source con cualquier agente de IA y cualquier modelo, sin atarte a un ecosistema cerrado.
• 🔧 Empieza por el modo remoto: activas el servidor en Tu cuenta → Integraciones, generas la clave (se muestra una sola vez) y la pegas en tu cliente.
• ⚡ Abre flujos multidireccionales: de diseño a código, de código a diseño y de diseño a documentación, además de generar tokens y variantes.
• 🎯 El prompt es un contrato, no una charla: da un rol, estructura como un brief, pide transformaciones e itera. Menos ruido, menos tokens.
• 📚 No es magia: verifica siempre la salida, valida URLs, APIs y estadísticas, y recurre a tu equipo antes que al modelo.

Preguntas frecuentes sobre los flujos de IA con Penpot ¶

¿Qué es Penpot MCP?

Penpot MCP es un servidor que implementa el Model Context Protocol para exponer tus ficheros de Penpot a un agente de IA. Está construido sobre la Plugin API de Penpot, es gratuito y open source, y permite que el agente lea y modifique elementos reales de tu diseño en lugar de inventárselos.

¿Necesito un cliente o un modelo concreto para usar Penpot MCP?

No. Penpot MCP es agnóstico: funciona con cualquier cliente compatible (Cursor, Claude Code, OpenCode) y cualquier modelo (Claude, Gemini, GPT). Para flujos complejos conviene un modelo potente, pero la elección es libre.

¿Cuál es la diferencia entre el modo remoto y el local?

El servidor remoto está alojado por Penpot, no instalas nada y es la vía más rápida para empezar. El servidor local se ejecuta en tu máquina, da más control y seguridad, y está pensado para usuarios cómodos con la terminal.

¿Cómo compruebo que Penpot MCP está conectado?

Pon tu cliente en modo Plan y pregúntale “What is the name of my current open Penpot file?”. Si responde con el nombre correcto de tu fichero, la conexión funciona. Es el test de “hola mundo” antes de ejecutar cualquier tarea.

¿Qué es un token y por qué me cobran por él?

Un token es la unidad de trabajo de un modelo de IA, equivale a grosso modo a un carácter de texto, y la mayoría de proveedores cobran por token de entrada y de salida. Como los tokens se correlacionan con el cómputo, un prompt más limpio reduce el gasto y el consumo energético.

¿Penpot MCP genera diseño responsive?

Por defecto Penpot genera maquetaciones con flex y grid según lo que mejor encaje. Para diseño responsive, lo recomendable es diseñar los breakpoints en Penpot, idealmente un board por cada uno, para darle contexto visual al agente.

¿Puede el agente acceder a varias librerías de mi equipo?

Sí. El MCP puede leer y usar de varias librerías conectadas a tu equipo, incluido un sistema de diseño partido en varias librerías o un set de iconos aparte. Puedes preguntarle sobre la estructura de un fichero compartido para entenderlo sin rastrearlo a mano.

¿Qué diferencia hay entre el modo Plan y el modo Build?

El modo Plan es de solo lectura: el agente inspecciona, lista y exporta, pero no edita tu fichero. El modo Build ejecuta la tarea y puede modificar tu trabajo. Empieza siempre en Plan para probar con seguridad.

¿Es seguro usar Penpot MCP con datos confidenciales?

Como con cualquier herramienta de terceros, evita compartir secretos, información personal o datos propietarios en tus prompts. Limita las carpetas y ficheros a los que das acceso, haz copia de seguridad antes de editar y revisa los términos del cliente y del modelo.

¿Penpot MCP sustituye a diseñadores y desarrolladores?

No. Los flujos de IA aceleran las partes verificables del trabajo, pero las decisiones de diseño y la verificación de la salida siguen siendo tarea humana. Trata el código generado como un pull request de un junior y recurre a la experiencia de tu equipo antes que al modelo.

Fuentes ¶

• Penpot Blog, Penpot AI workflows explained — qué son los flujos de IA, terminología y límites.
• Juan de la Cruz García, The designer’s guide to effective AI prompting — las nueve buenas prácticas de prompting token-aware.
• Penpot Help Center, Penpot MCP server — guía de configuración del servidor remoto y local.
• Penpot, MCP server — naturaleza agnóstica, abierta y multidireccional del servidor.
• Penpot, Set up Penpot MCP with OpenRouter and OpenCode in 6 steps — flujo completo con un cliente concreto.

🧨 Última oprtunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter