← Volver al listado de tecnologías ← Índice de OpenPencil

MCP Server y Claude Code

5 de abril de 2026 Por: Artiko

openpencilmcpclaude-codecursorwindsurfintegración

MCP Server y Claude Code

¿Qué es el protocolo MCP?

MCP (Model Context Protocol) es un estándar abierto creado por Anthropic que permite a los modelos de lenguaje comunicarse con herramientas externas de forma estructurada. En lugar de copiar y pegar JSON entre tu editor y una app, el modelo puede directamente llamar a las herramientas del sistema externo como si fueran funciones de código.

OpenPencil implementa un MCP server que expone el canvas del editor como un conjunto de herramientas invocables por cualquier cliente MCP compatible. Esto significa que desde Claude Code puedes crear, modificar y consultar diseños en OpenPencil sin salir de tu entorno de desarrollo.

sequenceDiagram
    participant D as Desarrollador
    participant CC as Claude Code
    participant MCP as OpenPencil MCP Server
    participant OP as OpenPencil Canvas

    D->>CC: "Diseña el componente UserCard"
    CC->>MCP: new_document({name: "UserCard"})
    MCP->>OP: Crea documento
    CC->>MCP: design_skeleton({prompt: "..."})
    MCP->>OP: Estructura inicial
    CC->>MCP: design_content({pageId: "..."})
    MCP->>OP: Contenido real
    CC->>MCP: design_refine({pageId: "..."})
    MCP->>OP: Estilos finales
    CC->>MCP: get_page_tree({pageId: "..."})
    MCP-->>CC: Árbol de nodos
    CC->>D: "UserCard diseñado. Exportando..."
    CC->>MCP: export_react({componentId: "..."})
    MCP-->>CC: Código React + Tailwind
    CC->>D: Muestra el código generado

Iniciar el MCP Server de OpenPencil

El MCP server de OpenPencil se inicia como un proceso separado que expone las herramientas de diseño vía el protocolo MCP:

# Iniciar el MCP server en el puerto por defecto (3333)
op mcp start

# Iniciar en un puerto específico
op mcp start --port 4444

# Iniciar con log detallado
op mcp start --verbose

# Iniciar con un documento específico ya abierto
op mcp start --file mi-proyecto.op

# El server acepta conexiones en:
# stdio (para Claude Code local)
# WebSocket ws://localhost:3333 (para integraciones remotas)

Configurar en Claude Code

Claude Code soporta MCP servers nativamente. La configuración se hace en ~/.claude/settings.json:

// ~/.claude/settings.json
{
  "mcpServers": {
    "openpencil": {
      "command": "op",
      "args": ["mcp", "start", "--stdio"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "OPENPENCIL_WORKSPACE": "/home/usuario/Diseños"
      }
    }
  }
}

La opción --stdio hace que el server use stdin/stdout en lugar de WebSocket, lo que es más eficiente para uso local con Claude Code.

Verificar la conexión

# En Claude Code, prueba que el MCP está disponible
/mcp list

# Deberías ver:
# ✓ openpencil - OpenPencil Design Tools (12 tools available)

# Listar herramientas disponibles
/mcp tools openpencil

Configuración con variables de entorno

Para no exponer la API key en el archivo de configuración:

# ~/.zshrc
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENPENCIL_WORKSPACE="$HOME/Diseños"

// ~/.claude/settings.json
{
  "mcpServers": {
    "openpencil": {
      "command": "op",
      "args": ["mcp", "start", "--stdio"],
      "env": {
        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
        "OPENPENCIL_WORKSPACE": "${OPENPENCIL_WORKSPACE}"
      }
    }
  }
}

Configurar en Cursor

Cursor usa el mismo protocolo MCP. La configuración va en .cursor/mcp.json dentro del proyecto (o en la configuración global de Cursor):

// .cursor/mcp.json
{
  "mcpServers": {
    "openpencil": {
      "command": "op",
      "args": ["mcp", "start", "--stdio"],
      "description": "OpenPencil design tools for creating and modifying UI designs",
      "env": {
        "OPENPENCIL_WORKSPACE": "./designs"
      }
    }
  }
}

En Cursor, puedes verificar el estado del MCP desde Settings → MCP Servers.

Configurar en Windsurf y Codex

Windsurf

// ~/.windsurf/mcp.json
{
  "servers": {
    "openpencil": {
      "transport": "stdio",
      "command": "op mcp start --stdio",
      "capabilities": ["design", "canvas", "export"]
    }
  }
}

GitHub Copilot (VS Code con extensión MCP)

// .vscode/settings.json
{
  "github.copilot.mcp.servers": {
    "openpencil": {
      "command": "op",
      "args": ["mcp", "start", "--stdio"]
    }
  }
}

Herramientas MCP disponibles

El MCP server expone 12 herramientas principales que Claude puede invocar:

`open_file`

Abre un archivo .op existente para trabajar con él:

// Claude lo invoca internamente así:
open_file({
  path: "./designs/dashboard.op"
})
// Respuesta: { documentId: "doc-abc123", pages: [...] }

`new_document`

Crea un nuevo documento de diseño:

new_document({
  name: "UserCard Component",
  width: 400,    // Ancho del frame inicial
  height: 300,   // Alto del frame inicial
  workspace: "./designs"
})
// Respuesta: { documentId: "doc-xyz", pageId: "page-1" }

`get_page_tree`

Obtiene el árbol de nodos de una página:

get_page_tree({
  documentId: "doc-abc123",
  pageId: "page-1"
})
// Respuesta: árbol JSON completo de todos los nodos

`find_nodes`

Busca nodos por criterios específicos:

find_nodes({
  documentId: "doc-abc123",
  filters: {
    type: "TEXT",           // Tipo de nodo
    name: "Button*",        // Patrón de nombre (glob)
    hasStyle: "fill-blue",  // Que tenga un estilo específico
    page: "all"             // En todas las páginas
  }
})

`get_node`

Obtiene todas las propiedades de un nodo específico:

get_node({
  documentId: "doc-abc123",
  nodeId: "node-789"
})
// Respuesta: objeto completo con todas las propiedades del nodo

`list_pages`

Lista todas las páginas del documento:

list_pages({
  documentId: "doc-abc123"
})
// Respuesta: [{id, name, nodeCount, thumbnailUrl}, ...]

`design_skeleton`

Primera fase del flujo de diseño: crea la estructura:

design_skeleton({
  documentId: "doc-abc123",
  pageId: "page-1",
  prompt: "Dashboard con sidebar de navegación, header con usuario y área principal con grid de métricas"
})
// Respuesta: { status: "completed", nodesCreated: 45, nextStep: "design_content" }

`design_content`

Segunda fase: rellena con contenido real:

design_content({
  documentId: "doc-abc123",
  pageId: "page-1",
  context: "App de analytics para ecommerce. Usuario: [email protected]"
})

`design_refine`

Tercera fase: aplica estilos y pulido visual:

design_refine({
  documentId: "doc-abc123",
  pageId: "page-1",
  brandTokens: {
    colorPrimary: "#2563EB",
    fontHeading: "Inter",
    fontBody: "DM Sans",
    borderRadius: 8
  }
})

`export_react`

Exporta un nodo o página a React + Tailwind:

export_react({
  documentId: "doc-abc123",
  nodeId: "component-btn-primary",  // Exportar componente específico
  options: {
    typescript: true,
    useShadcn: false,
    outputPath: "./src/components"
  }
})
// Respuesta: { code: "...", filename: "ButtonPrimary.tsx" }

`update_node`

Modifica propiedades de un nodo existente:

update_node({
  documentId: "doc-abc123",
  nodeId: "text-heading",
  properties: {
    content: "Nuevo título",
    fontSize: 32,
    fontWeight: 700,
    fills: [{ type: "SOLID", color: "#1E293B" }]
  }
})

`create_component`

Crea un nuevo componente con variantes:

create_component({
  documentId: "doc-abc123",
  pageId: "page-1",
  name: "Badge",
  variants: [
    { name: "success", props: { color: "#16A34A" } },
    { name: "error", props: { color: "#DC2626" } },
    { name: "warning", props: { color: "#D97706" } }
  ]
})

El flujo de diseño desde Claude Code

Flujo básico: un componente desde cero

El flujo más común es pedir a Claude que diseñe un componente y lo exporte directamente al proyecto:

# En Claude Code
Necesito un componente UserCard para mi app React.
El componente muestra: avatar circular del usuario, nombre completo, 
cargo, departamento y un badge de estado (online/offline/away).
Diseña el componente en OpenPencil y luego expórtalo a React + Tailwind 
en src/components/UserCard.tsx

Claude invocará internamente las herramientas en este orden:

flowchart TD
    A[new_document<br/>Crea documento UserCard] --> B[design_skeleton<br/>Estructura del componente]
    B --> C[design_content<br/>Avatar, nombre, cargo, badge]
    C --> D[design_refine<br/>Colores, tipografía, sombras]
    D --> E[get_page_tree<br/>Verifica el resultado]
    E --> F[export_react<br/>Genera código TypeScript]
    F --> G[Escribe archivo<br/>src/components/UserCard.tsx]

Flujo avanzado: sistema de diseño completo

Para proyectos más ambiciosos, Claude puede construir un sistema de diseño completo:

Necesito un design system para mi app SaaS de gestión de proyectos.
El stack es React + Tailwind CSS + shadcn/ui.
El branding es: moderno, minimalista, confiable.
Color primario: #2563EB (azul corporativo).

Por favor:
1. Crea el documento de design system en designs/system.op
2. Diseña y exporta estos componentes:
   - Button (4 variantes: primary, secondary, ghost, destructive)
   - Input (estados: default, focus, error, disabled)
   - Card (header, body, footer opcionales)
   - Badge (5 variantes de color + tamaños sm/md/lg)
   - Avatar (con imagen + fallback con iniciales)
3. Exporta todos a src/components/ui/ con TypeScript
4. Genera el archivo de tokens CSS en src/styles/tokens.css

Iterar sobre diseños existentes

Si ya tienes un archivo .op en tu proyecto:

Abre el archivo designs/dashboard.op.
En la página "Mobile", el componente "BottomNav" tiene el ícono de 
configuración equivocado. Reemplázalo con el ícono "settings" de Heroicons.
Luego exporta solo ese componente actualizado.

Claude usará open_file → find_nodes (busca “BottomNav”) → update_node → export_react.

Ejemplos de prompts para diseño con MCP

Componentes UI comunes

Diseña en OpenPencil y exporta a React:

[MODAL DE CONFIRMACIÓN]
- Overlay semi-transparente oscuro
- Card centrada (max 400px)
- Ícono de advertencia (Heroicons: exclamation-triangle)
- Título "¿Confirmar acción?"
- Descripción personalizable como prop
- Dos botones: "Cancelar" (ghost) y "Confirmar" (destructive)
- Animación de entrada: fade + scale desde el centro

Diseña en OpenPencil y exporta a React:

[SIDEBAR DE NAVEGACIÓN]
- Ancho: 260px, altura: 100vh
- Logo del app en la parte superior (placeholder)
- Sección "Principal": 5 items de nav con iconos
- Sección "Configuración": 3 items de nav
- Perfil del usuario en la parte inferior (avatar + nombre + logout)
- Estado active visible en el item actual
- Versión colapsada (solo iconos) como variante

Pantallas completas

Diseña en OpenPencil:

[PANTALLA DE ONBOARDING]
Paso 3 de 5: "Configura tu equipo"
- Progress bar en el top mostrando 60%
- Título grande y descripción
- Campo para nombre del equipo
- Grid de avatares para invitar miembros (input de email + botón add)
- Lista de miembros ya agregados con opción de eliminar
- Botones de navegación: "Anterior" y "Siguiente"
- Diseño limpio, mucho whitespace, tipografía Inter

Modificaciones sobre diseños existentes

En el archivo designs/landing.op, página "Desktop":
1. Busca la sección "Pricing" 
2. El plan "Pro" necesita el badge "Más popular" encima del título
3. Cambia el CTA del plan Pro de "Empezar" a "Empezar gratis 14 días"
4. Agrega un texto pequeño debajo: "Sin tarjeta de crédito"
5. Exporta la sección Pricing actualizada como PricingSection.tsx

Configuración del proyecto para equipos

Para que todo el equipo use la misma configuración de MCP, crea un archivo de configuración compartido en el repositorio:

// .openpencil/mcp-config.json (commiteado al repo)
{
  "workspace": "./designs",
  "defaultPage": {
    "width": 1440,
    "height": 900
  },
  "brandTokens": {
    "colorPrimary": "#2563EB",
    "colorSecondary": "#7C3AED",
    "fontHeading": "Inter",
    "fontBody": "DM Sans",
    "borderRadius": 8,
    "spacingBase": 4
  },
  "exportDefaults": {
    "framework": "react",
    "typescript": true,
    "outputDir": "./src/components/generated"
  }
}

// .cursor/mcp.json (commiteado al repo)
{
  "mcpServers": {
    "openpencil": {
      "command": "op",
      "args": ["mcp", "start", "--stdio", "--config", ".openpencil/mcp-config.json"]
    }
  }
}

El archivo mcp-config.json se commitea al repositorio (sin API keys), y cada desarrollador agrega su API key en su configuración local (~/.claude/settings.json o variables de entorno).

Debugging y troubleshooting

Ver logs del MCP server

# Iniciar con logs detallados
op mcp start --verbose --log-file ~/.openpencil/mcp.log

# Ver logs en tiempo real
tail -f ~/.openpencil/mcp.log

Problemas comunes

El MCP server no aparece en Claude Code

# Verificar que op está en el PATH
which op
op --version

# Reiniciar Claude Code después de cambiar settings.json
# En Claude Code: /restart

Error “Connection refused”

# Verificar que el server está corriendo
op mcp status

# Si no está corriendo, iniciarlo manualmente
op mcp start --stdio &

Las herramientas no responden

# Verificar que OpenPencil Desktop está abierto
# El MCP server necesita que la app esté corriendo
op start  # Abre la app de escritorio

# En otro terminal, iniciar el MCP server
op mcp start --stdio

Prueba manual de las herramientas MCP

Puedes probar las herramientas directamente desde Claude Code:

# Prueba rápida del MCP
Por favor usa la herramienta MCP "openpencil" para:
1. Crear un nuevo documento llamado "test"
2. Obtener la lista de páginas
3. Mostrarme el resultado

Resumen

En este capítulo has aprendido:

Qué es el protocolo MCP y cómo lo implementa OpenPencil
Iniciar el MCP server con op mcp start
Configurar el MCP en Claude Code, Cursor y Windsurf
Las 12 herramientas MCP disponibles y sus parámetros
El flujo completo de diseño desde Claude Code: skeleton → content → refine → export
Ejemplos de prompts para diseñar componentes y pantallas completas
Configuración compartida para equipos en el repositorio

En el próximo capítulo profundizaremos en las opciones de exportación de código.