Excalidraw

Un servidor MCP para crear, modificar y manipular dibujos de Excalidraw a través de una API.

Documentación

Servidor MCP de Excalidraw, CLI y Skill para Agentes

mcp-excalidraw-server brinda a los agentes de IA un lienzo Excalidraw en vivo sobre el que pueden dibujar, observar, refinar y guardar en tu repositorio. Tu agente crea diagramas de arquitectura y diagramas de flujo de forma programática, ve su propio trabajo mediante capturas de pantalla, corrige problemas de diseño y exporta archivos .excalidraw que puedes confirmar junto a tu código.

Un lienzo, tres formas de manejarlo:

Skill para Agente + CLI — recomendado para agentes de codificación (Claude Code, Codex CLI, Cursor, OpenCode): npx -y mcp-excalidraw-server <command>. Cero configuración, inicia el lienzo automáticamente, JSON componible de entrada/salida.
Servidor MCP — 26 herramientas sobre stdio para cualquier cliente del Model Context Protocol (Claude Desktop, Cursor, Codex CLI, Antigravity, ...). Habla MCP 2026-07-28 (server/discover, envoltura _meta por solicitud, llamadas a herramientas sin protocolo de inicio) y sigue siendo compatible con clientes de la era 2025 que abren con initialize.
API REST — HTTP simple para LangChain y frameworks personalizados.

El dibujo principal se ejecuta completamente en local (Node ≥ 20, licencia MIT) — sin claves de API. La conversión de Mermaid se ejecuta en el lienzo del navegador local; share es opcional y sube una escena cifrada a excalidraw.com.

Demo

AI agent drawing an architecture diagram on a live Excalidraw canvas via MCP

Un agente de IA crea un diagrama de arquitectura completo a partir de un solo prompt (velocidad 4x). Ver video completo en YouTube

Tabla de Contenidos

Demo
Qué Es
Cómo Nos Diferenciamos del MCP Oficial de Excalidraw
Novedades
Instalación
Skill para Agente
Referencia CLI
Configurar Clientes MCP
Herramientas MCP (26 en Total)
Inicio Rápido (Desde Código Fuente / Docker)
Pruebas
Preguntas Frecuentes
Solución de Problemas
Problemas Conocidos / Pendientes
Desarrollo
Licencia

Qué Es

Pídele a tu agente que "dibuje la arquitectura de este servicio" y producirá un diagrama Excalidraw real y editable — no una imagen de un solo uso. Como el agente puede consultar, capturar y actualizar elementos individuales, itera hasta que las etiquetas encajen, nada se superponga y las flechas se enruten limpiamente; luego exporta el resultado como un archivo .excalidraw que vive en tu repositorio y se actualiza cuando el código cambia.

Internamente hay dos procesos, un solo producto:

Servidor de lienzo: interfaz web de Excalidraw + API REST + sincronización en tiempo real por WebSocket (por defecto http://127.0.0.1:3000)
Una interfaz ligera de tu elección: el CLI, el servidor stdio de MCP o HTTP puro — todos manejan el mismo lienzo

Desde v1.1 el servidor de lienzo se inicia solo: los comandos CLI que manejan el lienzo (y el servidor MCP al lanzarse) lo generan automáticamente si nada está escuchando. status solo inspecciona el estado actual del servidor. Configura EXCALIDRAW_NO_AUTOSTART=1 para optar por no participar.

Cómo Nos Diferenciamos del MCP Oficial de Excalidraw

Excalidraw tiene un MCP oficial — un widget de chat que transmite un diagrama en línea desde un solo prompt (el modelo tiene dos herramientas: una referencia de formato y create_view). Es excelente para "dibújame un gato" en Claude o ChatGPT. Nosotros resolvemos un problema diferente: dar a los agentes de codificación un banco de trabajo de lienzo persistente.

	MCP Oficial de Excalidraw	Este Proyecto
Enfoque	Prompt de entrada, diagrama de salida (widget de un solo uso)	Control programático a nivel de elementos (CLI + 26 herramientas MCP)
Estado	Puntos de control dentro del widget de chat	Lienzo vivo persistente con sincronización en tiempo real
CRUD de elementos	Reenvío declarativo con marcadores de eliminación	Crear / leer / actualizar / eliminar completo por elemento
El agente ve el lienzo	No	`describe` (texto estructurado) + `screenshot` (imagen)
Refinamiento iterativo	Regenerar desde el punto de control	Dibujar → mirar → ajustar → mirar de nuevo, elemento por elemento
Herramientas de diseño	No	alinear, distribuir, agrupar / desagrupar, bloquear, duplicar
Entrada/Salida de archivos	Sin exportación orientada al modelo	Exportación/importación `.excalidraw` — diagramas como artefactos del repositorio
Instantáneas y reversión	Puntos de control del lado del widget	Instantáneas con nombre del lado del servidor
Conversión de Mermaid	No	`mermaid` / `create_from_mermaid`
URLs compartibles	Solo widget	`share` / `export_to_excalidraw_url`
Control de viewport	Animaciones de cámara	`set_viewport` (zoom para ajustar todo o elementos seleccionados, centrar en un elemento, zoom manual)
Funciona sin MCP	No	Sí — CLI + skill para agente + API REST
Multi-agente	Chat único	Múltiples agentes en el mismo lienzo simultáneamente

En resumen — El MCP oficial muestra diagramas Excalidraw en tu chat. Este proyecto le da a tu agente de codificación un banco de trabajo Excalidraw completo: un lienzo sobre el que puede dibujar, inspeccionar, refinar y confirmar en tu repositorio.

Novedades

Versión actual del paquete: 2.0.0. La línea de lanzamiento actual es v2.0 — Exportaciones de Grado de Intercambio y MCP 2026-07-28.

v2.0 — Exportaciones de Grado de Intercambio y MCP 2026-07-28

Cambio importante: Node >= 20 requerido (antes 18) — el SDK de TypeScript de MCP v2 establece el mínimo. Todo lo demás es compatible hacia atrás, incluidas las configuraciones existentes de clientes MCP.
Revisión del protocolo MCP 2026-07-28: los clientes modernos pueden llamar herramientas sin estado sin un protocolo de inicio (server/discover, envolturas _meta por solicitud); los clientes heredados basados en inicialización siguen funcionando sin cambios. (#98, gracias @anxkhn)
Las exportaciones se renderizan en todas partes ahora: los archivos .excalidraw / .excalidraw.md contienen elementos Excalidraw reales — etiquetas de formas y flechas como texto vinculado, enlaces de flechas en vivo — por lo que se abren correctamente en excalidraw.com y en el plugin de Obsidian Excalidraw en lugar de perder etiquetas (o ser re-guardados vacíos por el plugin). (#93, #95)
Exportaciones estables a nivel de bytes: ids, semillas y orden de claves deterministas — re-exportar una escena sin cambios es idéntico a nivel de bytes, por lo que los diagramas confirmados y los archivos de bóveda nunca producen diffs fantasma en git, y las referencias de bloque de Obsidian sobreviven a las re-exportaciones.
Correcciones de bóveda de Obsidian: los archivos .excalidraw.md de Windows/CRLF se importan correctamente (#94, gracias @cason-miles); las referencias de bloque ## Text Elements ahora también cubren las etiquetas de formas.
Los campos de elementos nunca se descartan silenciosamente: las propiedades desconocidas de Excalidraw (containerId, textAlign, originalText, ...) pasan por el servidor intactas — corrige el texto editado en el navegador que desaparecía después de la sincronización. (#92, gracias @junuxyz)
La conversión de Mermaid se fusiona en el lienzo existente en lugar de reemplazarlo, y cada pestaña del navegador mantiene exactamente una conexión WebSocket (sin más etiquetas duplicadas). (#91)
Control de viewport: set_viewport gana scrollToElementIds (zoom para ajustar múltiples elementos) y viewportZoomFactor, con validación estricta de modo único y reporte de errores real. (#86, gracias @acercyc)
Modo oscuro: el marco de la página del lienzo sigue el tema del editor y lo persiste entre recargas. (#89, gracias @danielsvane)

v1.1 — CLI-Primero

CLI de primera clase: cada capacidad es ahora un comando componible — npx -y mcp-excalidraw-server add|query|describe|screenshot|export|import|mermaid|snapshot|arrange|share|... — JSON en stdout, códigos de salida significativos. También instalado como el alias excalidraw-canvas.
Cero configuración: los comandos CLI que manejan el lienzo y el servidor MCP inician automáticamente el servidor de lienzo si no está en ejecución (cierra #66). Opta por no participar con EXCALIDRAW_NO_AUTOSTART=1.
apply: parches multi-operación ({"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}) en una sola invocación.
install-skill: npx -y mcp-excalidraw-server install-skill --dir <skills-root> copia el skill portátil del agente en el directorio que tu agente elija (proyecto o global), reemplazando limpiamente versiones anteriores.
El skill ahora es CLI-primero y ya no necesita un repositorio clonado o un servidor MCP configurado para funcionar.
Consultas tipadas: query --filter locked=true --filter label.text=API — booleanos, números y claves anidadas funcionan.
Internos: biblioteca central compartida (src/core/) detrás del CLI y el servidor MCP; los groupIds del lienzo son la fuente de verdad para la agrupación (desagrupar ahora funciona entre reinicios); node-fetch eliminado; metadatos de versión MCP derivados de package.json; el servidor de lienzo escribe un archivo pid y se apaga limpiamente.

Instalación

El único requisito previo es Node.js ≥ 20.

Lo más fácil: deja que tu agente lo instale

Copia esto en tu agente de codificación — instala el skill portátil en el directorio de skills de proyecto/global que ese agente ya sabe usar, luego lo verifica dibujando un diagrama de prueba:

Install the Excalidraw canvas toolkit so you can draw diagrams for me:

1. Choose the right skill directory for this agent and scope (project or global).
2. Run: npx -y mcp-excalidraw-server install-skill --dir <that-skills-directory>
3. Read the installed excalidraw-skill/SKILL.md so you know the drawing workflow.
4. Start the canvas with: npx -y mcp-excalidraw-server start
   then tell me to open http://127.0.0.1:3000 in my browser (screenshots need an open tab).
5. Draw a small test diagram — two labeled boxes connected by an arrow — take a
   screenshot, and show me the result to confirm everything works.

Instalación manual

Eres...	Instala con	Luego
Agente de codificación moderno	`npx -y mcp-excalidraw-server install-skill --dir <skills-root>`	Deja que el agente elija el alcance de proyecto/global y su raíz de skills
Atajo de Claude Code	`npx -y mcp-excalidraw-server install-skill`	Instala en `~/.claude/skills` para compatibilidad hacia atrás
Atajo de Codex	`npx -y mcp-excalidraw-server install-skill --target codex`	Instala en `~/.codex/skills` para compatibilidad hacia atrás
Usuario de cliente MCP (Claude Desktop, Cursor, ...)	Agrega la configuración npx a continuación	Consulta Configurar Clientes MCP
Usuario de CLI / scripting	Nada — `npx -y mcp-excalidraw-server <command>`	Consulta Referencia CLI
Colaborador / desde código fuente	`git clone` + `npm ci` + `npm run build`	Consulta Inicio Rápido (Desde Código Fuente / Docker)

No hay configuración separada del servidor: cualquier comando de dibujo inicia automáticamente el servidor de lienzo local en http://127.0.0.1:3000.

Inicio Rápido en 60 Segundos (CLI)

Sin clonar, sin configurar:

# start the canvas (drawing commands auto-start it too) and open it
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # browser tab enables screenshots & mermaid

# draw something
echo '[
  {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
  {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
  {"type":"arrow","x":0,"y":0,"startElementId":"api","endElementId":"db","text":"SQL"}
]' | npx -y mcp-excalidraw-server add

# let your agent see its work
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# diagrams as repo artifacts
mkdir -p docs
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw

# or straight into an Obsidian vault (.md extension → Obsidian Excalidraw plugin format)
npx -y mcp-excalidraw-server export --out ~/vault/diagrams/architecture.excalidraw.md

Dale a tu agente el manual completo:

npx -y mcp-excalidraw-server install-skill --dir <skills-root>
npx -y mcp-excalidraw-server install-skill --print-source  # inspect bundled source path

Nota de seguridad: El servidor de lienzo se vincula solo a 127.0.0.1 por defecto. Si lo expones en una interfaz de red (HOST=0.0.0.0), coloca controles de acceso a nivel de red al frente — la API no tiene autenticación incorporada.

Skill para Agente

El skill en skills/excalidraw-skill/ enseña a los agentes el flujo de trabajo completo — planificación del diseño, el ciclo de calidad de captura-verifica-corrige, enrutamiento de flechas, anti-patrones, instantáneas y entrada/salida de archivos. Funciona a través del CLI (preferido, cero configuración), herramientas MCP (si están configuradas) o REST puro — en ese orden.

npx -y mcp-excalidraw-server install-skill --dir <skills-root>

El comando copia el directorio excalidraw-skill/ incluido en <skills-root>/excalidraw-skill. Deja que tu agente elija si esa raíz debe ser a nivel de proyecto o global. Volver a ejecutar install-skill actualiza en el lugar — reemplaza el directorio de destino, por lo que los archivos eliminados aguas arriba no permanecen.

Donde el skill brilla:

Diagramas como artefactos de código: exporta archivos .excalidraw al repositorio, confírmalos, re-importa + refina cuando la arquitectura cambie.
Bóvedas de Obsidian: exporta con una extensión .excalidraw.md y el archivo se abre nativamente en el plugin de Obsidian Excalidraw — sin advertencia de modo de compatibilidad, las referencias de bloque y la sincronización funcionan; import lee tanto archivos de bóveda comprimidos con lz-string como planos.
Diagramas auto-verificables: el agente captura su propio trabajo y corrige truncamientos/superposiciones antes de declararlo terminado.
Entornos sin MCP: trabajos de CI, shells simples y frameworks obtienen las mismas capacidades a través del CLI.

Referencia CLI

npx -y mcp-excalidraw-server <command> o (después de npm i -g mcp-excalidraw-server) excalidraw-canvas <command>.

Convenciones: resultados JSON en stdout — excepto describe (texto plano por diseño) y salida de contenido crudo cuando se omite --out (export imprime el JSON de la escena, screenshot --format svg imprime SVG). Diagnósticos en stderr. Códigos de salida: 0 ok, 1 error, 2 uso, 3 lienzo inalcanzable, 4 pestaña del navegador requerida. URL del lienzo desde EXPRESS_SERVER_URL o --url. Los comandos que manejan el lienzo inician automáticamente el servidor; status solo reporta el estado actual. start explícito anula la exclusión de EXCALIDRAW_NO_AUTOSTART=1 (es intención del usuario, no inicio automático).

Comando	Descripción
`start` / `stop` / `status`	Gestiona el servidor del lienzo (en segundo plano; `stop` verifica la identidad del servidor en vivo mediante `/health` antes de enviar señales)
`add [file\|-]`	Crea elementos por lotes desde un array JSON (archivo o stdin); `--one '{...}'` para un solo elemento
`apply [file\|-]`	Parche multioperación en una sola llamada: `{"create":[...],"update":[{"id":"a","set":{...}}],"delete":["id"]}`
`get <id>` / `delete <id...>`	Leer / eliminar elementos
`update <id> --set '{...}'`	Actualiza un elemento
`query`	`--type`, `--bbox x0,y0,x1,y1`, `--filter k=v` (claves anidadas y tipadas), `--filter-json '{...}'`
`describe`	Resumen de escena legible por IA (texto plano)
`screenshot`	`--out f.png`, `--format png\|svg`, `--no-background` (requiere pestaña del navegador)
`export [--out f.excalidraw] [--format json\|obsidian]` / `import [file\|-] [--replace]`	Entrada/salida de archivos de escena: una ruta de salida `.md` escribe el formato `.excalidraw.md` de Obsidian; `import` lo lee de vuelta
`mermaid [file\|-]`	Mermaid → lienzo (requiere pestaña del navegador)
`snapshot save\|list\|restore <name>`	Instantáneas con nombre
`arrange align\|distribute\|group\|ungroup\|lock\|unlock\|duplicate`	Operaciones de diseño (`--ids a,b,c`, `--to left\|horizontal\|...`)
`share`	Carga cifrada → URL compartible de excalidraw.com
`clear --yes`	Limpia el lienzo
`install-skill [--dir <skills-root>]`	Instala la habilidad portable del agente

Las etiquetas y los enlaces de flechas usan el formato amigable para agentes en toda la CLI: "text" en cualquier forma, "startElementId"/"endElementId" en flechas — la normalización es automática.

Configurar clientes MCP

El servidor MCP se ejecuta sobre stdio. Desde v1.1, la configuración más simple es npx — sin clonar, sin rutas absolutas, y el lienzo se inicia automáticamente:

Variables de entorno

Variable	Descripción	Predeterminado
`EXPRESS_SERVER_URL`	URL del servidor del lienzo	`http://127.0.0.1:3000`
`ENABLE_CANVAS_SYNC`	Habilita la sincronización del lienzo en tiempo real	`true`
`EXCALIDRAW_NO_AUTOSTART`	Establece `1` para deshabilitar el inicio automático del lienzo	(sin establecer)
`EXCALIDRAW_EXPORT_DIR`	Directorio base donde las exportaciones de archivos MCP pueden escribir	directorio de trabajo actual
`PORT` / `HOST`	Dirección de enlace del servidor del lienzo	`3000` / `127.0.0.1`

Claude Desktop

Ubicación de configuración:

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

npx (recomendado)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Local (node)

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Claude Code

npx (recomendado)

claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server

Consejo: para agentes de codificación, la habilidad + CLI a menudo supera la configuración MCP por completo — deja que el agente elija su raíz de habilidad y luego ejecuta npx -y mcp-excalidraw-server install-skill --dir <skills-root>.

Local (node) - Nivel de usuario (disponible en todos los proyectos):

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

Docker

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Gestionar servidores:

claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server

Cursor

Ubicación de configuración: .cursor/mcp.json en la raíz de tu proyecto (o ~/.cursor/mcp.json para configuración global)

npx (recomendado)

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Docker

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

Codex CLI

npx (recomendado)

codex mcp add excalidraw -- npx -y mcp-excalidraw-server

Docker

codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Gestionar servidores:

codex mcp list              # List configured servers
codex mcp remove excalidraw # Remove a server

OpenCode

Ubicación de configuración: ~/.config/opencode/opencode.json o a nivel de proyecto opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["npx", "-y", "mcp-excalidraw-server"],
      "enabled": true
    }
  }
}

Antigravity (Google)

Ubicación de configuración: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

Notas

Redes Docker: Usa host.docker.internal para alcanzar el servidor del lienzo que se ejecuta en tu máquina host. En Linux, puede que necesites --add-host=host.docker.internal:host-gateway o usar 172.17.0.1. La imagen MCP de Docker establece EXCALIDRAW_NO_AUTOSTART=1 (no tiene compilación de frontend) — ejecuta el lienzo como su propio contenedor.
Almacenamiento en memoria: El servidor del lienzo almacena elementos en memoria. Reiniciar el servidor borra todos los elementos — usa export / snapshot para persistencia.

Herramientas MCP (26 en total)

Categoría	Herramientas
CRUD de elementos	`create_element`, `get_element`, `update_element`, `delete_element`, `query_elements`, `batch_create_elements`, `duplicate_elements`
Diseño	`align_elements`, `distribute_elements`, `group_elements`, `ungroup_elements`, `lock_elements`, `unlock_elements`
Conciencia de escena	`describe_scene`, `get_canvas_screenshot`
Entrada/salida de archivos	`export_scene`, `import_scene`, `export_to_image`, `export_to_excalidraw_url`, `create_from_mermaid`
Gestión de estado	`clear_canvas`, `snapshot_scene`, `restore_snapshot`
Viewport	`set_viewport`
Guía de diseño	`read_diagram_guide`
Recursos	`get_resource`

Los esquemas completos se pueden descubrir mediante tools/list o en skills/excalidraw-skill/references/cheatsheet.md.

El enfoque de grupo del viewport puede ajustar el encuadre con viewportZoomFactor:

{
  "scrollToElementIds": ["id1", "id2", "id3"],
  "viewportZoomFactor": 0.85
}

scrollToElementIds hace zoom para ajustar cada elemento solicitado, mientras que scrollToElementId centra un elemento sin cambiar el zoom actual. Especifica solo un modo de viewport por solicitud. viewportZoomFactor acepta valores mayores que 0 y como máximo 1.

Inicio rápido (desde fuente / Docker)

Desde fuente (Node >= 20):

npm ci
npm run build
PORT=3000 npm run canvas          # canvas server (terminal 1)
node dist/index.js                # MCP server over stdio (terminal 2, usually launched by your MCP client)
node dist/bin.js status           # or drive the CLI straight from the build

Servidor del lienzo Docker:

docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

Imagen del servidor MCP: ghcr.io/yctimlin/mcp_excalidraw:latest (stdio; apunta EXPRESS_SERVER_URL al contenedor del lienzo).

Pruebas

Prueba de humo CLI

npx -y mcp-excalidraw-server start
npx -y mcp-excalidraw-server status
npx -y mcp-excalidraw-server add --one '{"type":"rectangle","x":100,"y":100,"width":300,"height":200}'
npx -y mcp-excalidraw-server describe

Prueba de humo del lienzo (HTTP)

curl http://127.0.0.1:3000/health

Prueba de regresión de enlace local

npm run test:bind

Pruebas de regresión del lienzo en navegador

Estas pruebas de Chromium compilan la aplicación e inician un servidor localhost aislado. Cubren recarga/reconexión de marcos, escenas mixtas, protección de sincronización ante fallos de carga, respuestas obsoletas, borrado/eliminación, importaciones de Mermaid y exportación SVG. Se niegan a reutilizar un servidor existente; establece CANVAS_TEST_PORT si el puerto 51910 está ocupado.

npx playwright install chromium
npm run type-check:frontend
npm run test:canvas

Prueba de cable MCP Stdio

Impulsa dist/index.js con marcos JSON-RPC crudos y verifica ambas eras de protocolo: server/discover, llamadas a herramientas enviadas sin ningún protocolo de enlace, rechazo de revisiones de protocolo no compatibles y envolturas _meta malformadas, y la ruta heredada initialize.

npm run test:mcp

Prueba de humo MCP (Inspector MCP)

Listar herramientas:

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list

Crear un rectángulo:

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200

Capturas de pantalla del frontend (agent-browser)

Si usas agent-browser para comprobaciones de UI:

agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png

Preguntas frecuentes

¿En qué se diferencia esto del MCP oficial de Excalidraw?

El MCP oficial de Excalidraw es un widget de chat: escribes un prompt y transmite un diagrama a la conversación (el modelo obtiene dos herramientas). Este proyecto es un banco de trabajo para agentes de codificación: un lienzo local persistente con creación/lectura/actualización/eliminación a nivel de elemento, herramientas de diseño, capturas de pantalla que el modelo puede ver, instantáneas y entrada/salida de archivos .excalidraw — manejable mediante CLI, MCP o REST. Consulta la tabla de comparación completa.

¿Con qué herramientas de IA funciona?

Claude Code, Claude Desktop, Cursor, Codex CLI, OpenCode y Google Antigravity están documentados abajo — pero cualquier agente que pueda ejecutar comandos de shell puede usar la CLI, cualquier cliente MCP puede usar el servidor MCP, y cualquier otra cosa (LangChain, aplicaciones personalizadas) puede usar la API REST.

¿Puede la IA ver realmente el diagrama que dibujó?

Sí — esa es la característica principal. describe devuelve un resumen de texto estructurado (ids, posiciones, etiquetas, conexiones) y screenshot devuelve un PNG renderizado. Los agentes usan ambos para detectar etiquetas truncadas, superposiciones y mal enrutamiento de flechas, y luego los corrigen elemento por elemento.

¿Necesito tener un navegador abierto?

Solo para funciones que dependen de la renderización: capturas de pantalla, exportación PNG/SVG, control del viewport y conversión de Mermaid (se renderizan en el frontend de Excalidraw). Crear, consultar, actualizar elementos y exportar JSON .excalidraw funcionan sin interfaz gráfica. La CLI sale con el código 4 y te indica cuándo se necesita una pestaña del navegador.

¿Mis diagramas son persistentes?

El lienzo está en memoria por diseño (reiniciar = lienzo en blanco). Persiste exportando archivos .excalidraw a tu repositorio (export --out docs/architecture.excalidraw) o con snapshots con nombre mientras trabajas. Vuelve a import un archivo para seguir refinándolo más tarde.

¿Los enlaces compartidos de excalidraw.com son privados?

share cifra la escena localmente con AES-GCM antes de subirla; la clave de descifrado solo está en el fragmento de la URL, que el servidor de excalidraw.com nunca ve. Cualquiera a quien le des el enlace completo puede ver el diagrama.

¿Necesita una clave API o un servicio en la nube?

No se requiere clave API. El dibujo principal se ejecuta localmente bajo licencia MIT. La única llamada saliente es la carga opcional share a excalidraw.com.

¿Puedo usarlo sin configurar MCP?

Sí — ese es el camino recomendado para agentes de codificación: npx -y mcp-excalidraw-server install-skill --dir <skills-root> y el agente maneja todo a través de la CLI. La configuración MCP solo se necesita para clientes de chat como Claude Desktop.

Solución de problemas

Código de salida CLI 3 (lienzo inalcanzable): el servidor no se está ejecutando para un comando de inspección como status, el inicio automático está deshabilitado (EXCALIDRAW_NO_AUTOSTART=1), o EXPRESS_SERVER_URL apunta a un host que no es de bucle local. Ejecuta start explícitamente o corrige las variables de entorno.
Código de salida CLI 4 (se requiere navegador): las capturas de pantalla, la exportación de imágenes, el viewport y la conversión de mermaid se renderizan en el frontend — abre http://127.0.0.1:3000 en un navegador y reintenta.
El lienzo no se actualiza: confirma que EXPRESS_SERVER_URL apunta al servidor del lienzo en ejecución (status muestra la URL en uso).
Las actualizaciones/eliminaciones fallan después de la creación por lotes: asegúrate de estar en una compilación que incluya la corrección de preservación de id por lotes (fusionada mediante PR #34).

Problemas conocidos / Pendientes

Almacenamiento persistente: Los elementos se almacenan en memoria — reiniciar el servidor borra todo. Usa export / instantáneas como solución alternativa.
La exportación de imágenes requiere un navegador: las capturas de pantalla y la exportación de imágenes dependen del frontend para hacer la renderización real. Se planea un modo de renderización sin interfaz gráfica.

¡Las contribuciones son bienvenidas!

Desarrollo

npm run type-check
npm run build
npm run cli -- status      # run the CLI from the local build
npm run sync:skills        # after editing skills/excalidraw-skill, sync the repo-local agent copy

Los informes de errores y las solicitudes de extracción son bienvenidos en GitHub issues. Si este proyecto te ayuda, una ⭐ ayuda a otros a encontrarlo.

Licencia

MIT © yctimlin — no afiliado con el equipo de Excalidraw. Excalidraw es su propio proyecto con licencia MIT; este kit de herramientas se basa en él con cariño.

Enlaces: paquete npm · GitHub · Issues · Video de demostración