Excalidraw

Um servidor MCP para criar, modificar e manipular desenhos do Excalidraw por meio de uma API.

Documentação

Servidor MCP Excalidraw, CLI e Skill de Agente

mcp-excalidraw-server dá aos agentes de IA um canvas Excalidraw ao vivo no qual podem desenhar, visualizar, refinar e salvar no seu repositório. Seu agente cria diagramas de arquitetura e fluxogramas programaticamente, vê o próprio trabalho via capturas de tela, corrige problemas de layout e exporta arquivos .excalidraw que você pode versionar junto com seu código.

Um canvas, três formas de usá-lo:

Skill de Agente + CLI — recomendado para agentes de codificação (Claude Code, Codex CLI, Cursor, OpenCode): npx -y mcp-excalidraw-server <command>. Zero configuração, inicia o canvas automaticamente, JSON composto de entrada/saída.
Servidor MCP — 26 ferramentas via stdio para qualquer cliente Model Context Protocol (Claude Desktop, Cursor, Codex CLI, Antigravity, ...). Fala MCP 2026-07-28 (server/discover, envelope _meta por requisição, chamadas de ferramenta sem handshake) e permanece compatível com clientes da era 2025 que abrem com initialize.
API REST — HTTP simples para LangChain e frameworks personalizados.

O desenho principal roda totalmente local (Node ≥ 20, licença MIT) — sem chaves de API. A conversão Mermaid roda no canvas do navegador local; share é opcional e envia uma cena criptografada para excalidraw.com.

Demonstração

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

Agente de IA cria um diagrama de arquitetura completo a partir de um único prompt (4x velocidade). Assista ao vídeo completo no YouTube

Sumário

Demonstração
O Que É
Como Diferimos do MCP Oficial do Excalidraw
Novidades
Instalação
Skill de Agente
Referência da CLI
Configurar Clientes MCP
Ferramentas MCP (26 no Total)
Início Rápido (A partir do Código-Fonte / Docker)
Testes
FAQ
Solução de Problemas
Problemas Conhecidos / TODO
Desenvolvimento
Licença

O Que É

Peça ao seu agente para "desenhar a arquitetura deste serviço" e ele produz um diagrama Excalidraw real e editável — não uma imagem descartável. Como o agente pode consultar, capturar a tela e atualizar elementos individuais, ele itera até que os rótulos caibam, nada se sobreponha e as setas tenham roteamento limpo; então exporta o resultado como um arquivo .excalidraw que vive no seu repositório e é atualizado quando o código muda.

Por baixo dos panos, há dois processos, um produto:

Servidor de canvas: interface web do Excalidraw + API REST + sincronização em tempo real via WebSocket (padrão http://127.0.0.1:3000)
Um front-end fino de sua escolha: a CLI, o servidor stdio MCP ou HTTP puro — todos controlam o mesmo canvas

Desde a v1.1, o servidor de canvas inicia sozinho: comandos CLI que controlam o canvas (e o servidor MCP na inicialização) o iniciam automaticamente se nada estiver escutando. status apenas inspeciona o estado atual do servidor. Defina EXCALIDRAW_NO_AUTOSTART=1 para desativar.

Como Diferimos do MCP Oficial do Excalidraw

O Excalidraw tem um MCP oficial — um widget de chat que transmite um diagrama inline a partir de um único prompt (o modelo recebe duas ferramentas: uma referência de formato e create_view). É ótimo para "desenhe um gato para mim" no Claude ou ChatGPT. Resolvemos um problema diferente: dar a agentes de codificação uma bancada de trabalho com canvas persistente.

	MCP Oficial do Excalidraw	Este Projeto
Abordagem	Prompt entra, diagrama sai (widget de uso único)	Controle programático em nível de elemento (CLI + 26 ferramentas MCP)
Estado	Checkpoints dentro do widget de chat	Canvas persistente ao vivo com sincronização em tempo real
CRUD de elementos	Reenvio declarativo com marcadores de exclusão	Create / read / update / delete completo por elemento
IA vê o canvas	Não	`describe` (texto estruturado) + `screenshot` (imagem)
Refinamento iterativo	Regenerar a partir do checkpoint	Desenhar → olhar → ajustar → olhar novamente, elemento por elemento
Ferramentas de layout	Não	alinhar, distribuir, agrupar / desagrupar, bloquear, duplicar
I/O de arquivos	Sem exportação voltada ao modelo	Exportação/importação `.excalidraw` — diagramas como artefatos do repositório
Snapshot e rollback	Checkpoints no lado do widget	Snapshots nomeados no lado do servidor
Conversão Mermaid	Não	`mermaid` / `create_from_mermaid`
URLs compartilháveis	Somente no widget	`share` / `export_to_excalidraw_url`
Controle de viewport	Animações de câmera	`set_viewport` (zoom para caber em tudo ou em elementos selecionados, centralizar em um elemento, zoom manual)
Funciona sem MCP	Não	Sim — CLI + skill de agente + API REST
Multiagente	Chat único	Vários agentes no mesmo canvas simultaneamente

Resumo — O MCP oficial mostra diagramas Excalidraw no seu chat. Este projeto dá ao seu agente de codificação uma bancada Excalidraw completa: um canvas no qual ele pode desenhar, inspecionar, refinar e versionar no seu repositório.

Novidades

Versão atual do pacote: 2.0.0. A linha de versão atual é v2.0 — Exportações de Nível de Intercâmbio e MCP 2026-07-28.

v2.0 — Exportações de Nível de Intercâmbio e MCP 2026-07-28

Quebra: Node >= 20 obrigatório (antes era 18) — o SDK TypeScript MCP v2 define o mínimo. Todo o resto é compatível com versões anteriores, incluindo configurações existentes de clientes MCP.
Revisão do protocolo MCP 2026-07-28: clientes modernos podem chamar ferramentas sem estado, sem handshake de inicialização (server/discover, envelopes _meta por requisição); clientes legados baseados em inicialização continuam funcionando sem alterações. (#98, agradecimentos a @anxkhn)
Exportações renderizam em qualquer lugar agora: arquivos .excalidraw / .excalidraw.md contêm elementos Excalidraw reais — rótulos de formas e setas como texto vinculado, vínculos de seta ao vivo — para que abram corretamente em excalidraw.com e no plugin Obsidian Excalidraw, em vez de perder rótulos (ou serem re-salvos vazios pelo plugin). (#93, #95)
Exportações byte-estáveis: ids, seeds e ordem de chaves determinísticos — reexportar uma cena inalterada é byte-idêntico, então diagramas versionados e arquivos de vault nunca produzem diffs fantasma no git, e referências de bloco do Obsidian sobrevivem a reexportações.
Correções no vault do Obsidian: arquivos .excalidraw.md Windows/CRLF importam corretamente (#94, agradecimentos a @cason-miles); referências de bloco ## Text Elements agora cobrem também rótulos de formas.
Campos de elementos nunca são descartados silenciosamente: propriedades Excalidraw desconhecidas (containerId, textAlign, originalText, ...) passam pelo servidor intactas — corrige texto editado no navegador que desaparecia após a sincronização. (#92, agradecimentos a @junuxyz)
A conversão Mermaid mescla no canvas existente em vez de substituí-lo, e cada aba do navegador mantém exatamente uma conexão WebSocket (sem mais rótulos duplicados). (#91)
Controle de viewport: set_viewport ganha scrollToElementIds (zoom para caber em múltiplos elementos) e viewportZoomFactor, com validação estrita de modo único e relatório de erros real. (#86, agradecimentos a @acercyc)
Modo escuro: o chrome da página do canvas segue o tema do editor e o persiste entre recarregamentos. (#89, agradecimentos a @danielsvane)

v1.1 — CLI em Primeiro Lugar

CLI de primeira classe: toda capacidade agora é um comando composto — npx -y mcp-excalidraw-server add|query|describe|screenshot|export|import|mermaid|snapshot|arrange|share|... — JSON no stdout, códigos de saída significativos. Também instalado como alias excalidraw-canvas.
Zero configuração: comandos CLI que controlam o canvas e o servidor MCP iniciam automaticamente o servidor de canvas se ele não estiver rodando (fecha #66). Desative com EXCALIDRAW_NO_AUTOSTART=1.
apply: patches multi-operação ({"create":[...],"update":[{"id":"a","set":{...}}],"delete":[...]}) em uma única invocação.
install-skill: npx -y mcp-excalidraw-server install-skill --dir <skills-root> copia a skill de agente portátil para o diretório que seu agente escolher (projeto ou global), substituindo limpo versões mais antigas.
A skill agora é CLI em primeiro lugar e não precisa mais de repositório clonado ou servidor MCP configurado para funcionar.
Consultas tipadas: query --filter locked=true --filter label.text=API — booleanos, números e chaves aninhadas funcionam.
Internos: biblioteca central compartilhada (src/core/) por trás da CLI e do servidor MCP; groupIds do canvas são a fonte da verdade para agrupamento (desagrupar agora funciona entre reinicializações); node-fetch removido; metadados de versão MCP derivados de package.json; o servidor de canvas grava um pidfile e encerra limpo.

Instalação

O único pré-requisito é Node.js ≥ 20.

Mais fácil: deixe seu agente instalar

Copie isto para o seu agente de codificação — ele instala a skill portátil no diretório de skills de projeto/global que o agente já sabe usar e, em seguida, verifica desenhando um diagrama de teste:

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.

Instalação manual

Você é...	Instale com	Depois
Agente de codificação moderno	`npx -y mcp-excalidraw-server install-skill --dir <skills-root>`	Deixe o agente escolher o escopo projeto/global e a raiz de skills
Atalho do Claude Code	`npx -y mcp-excalidraw-server install-skill`	Instala em `~/.claude/skills` para compatibilidade com versões anteriores
Atalho do Codex	`npx -y mcp-excalidraw-server install-skill --target codex`	Instala em `~/.codex/skills` para compatibilidade com versões anteriores
Usuário de cliente MCP (Claude Desktop, Cursor, ...)	Adicione a configuração npx abaixo	Veja Configurar Clientes MCP
Usuário de CLI / scripts	Nada — `npx -y mcp-excalidraw-server <command>`	Veja Referência da CLI
Contribuidor / a partir do código-fonte	`git clone` + `npm ci` + `npm run build`	Veja Início Rápido (a partir do Código-Fonte / Docker)

Não há configuração separada de servidor: qualquer comando de desenho inicia automaticamente o servidor de canvas local em http://127.0.0.1:3000.

Início Rápido em 60 Segundos (CLI)

Sem clone, sem configuração:

# 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

Dê ao seu agente o 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 segurança: O servidor de canvas vincula 127.0.0.1 apenas por padrão. Se você o expor em uma interface de rede (HOST=0.0.0.0), coloque controles de acesso em nível de rede na frente — a API não tem autenticação embutida.

Skill de Agente

A skill em skills/excalidraw-skill/ ensina aos agentes o fluxo de trabalho completo — planejamento de layout, o loop de qualidade screenshot-verificar-corrigir, roteamento de setas, anti-padrões, snapshots e I/O de arquivos. Funciona via CLI (preferido, zero configuração), ferramentas MCP (se configuradas) ou REST puro — nessa ordem.

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

O comando copia o diretório excalidraw-skill/ incluído para <skills-root>/excalidraw-skill. Deixe seu agente escolher se essa raiz deve ser em nível de projeto ou global. Reexecutar install-skill atualiza no lugar — ele substitui o diretório de destino, então arquivos removidos upstream não ficam para trás.

Onde a skill se destaca:

Diagramas como artefatos de código: exporte arquivos .excalidraw para o repositório, faça commit, reimporte + refine quando a arquitetura mudar.
Vaults do Obsidian: exporte com extensão .excalidraw.md e o arquivo abre nativamente no plugin Obsidian Excalidraw — sem aviso de modo de compatibilidade, referências de bloco e sincronização funcionam; import lê de volta arquivos de vault tanto em texto simples quanto compactados com lz-string.
Diagramas autoverificáveis: o agente captura a tela do próprio trabalho e corrige truncamento/sobreposição antes de declarar concluído.
Ambientes sem MCP: jobs de CI, shells simples e frameworks obtêm as mesmas capacidades via CLI.

Referência da CLI

npx -y mcp-excalidraw-server <command> ou (após npm i -g mcp-excalidraw-server) excalidraw-canvas <command>.

Convenções: resultados JSON no stdout — exceto describe (texto simples por design) e saída de conteúdo bruto quando --out é omitido (export imprime o JSON da cena, screenshot --format svg imprime SVG). Diagnósticos no stderr. Códigos de saída: 0 ok, 1 erro, 2 uso, 3 canvas inacessível, 4 aba do navegador necessária. URL do canvas de EXPRESS_SERVER_URL ou --url. Comandos que controlam o canvas iniciam automaticamente o servidor; status apenas relata o estado atual. start explícito substitui a desativação EXCALIDRAW_NO_AUTOSTART=1 (é intenção do usuário, não início automático).

Comando	Descrição
`start` / `stop` / `status`	Gerencia o servidor de canvas (em segundo plano; `stop` verifica a identidade do servidor ativo via `/health` antes de sinalizar)
`add [file\|-]`	Cria elementos em lote a partir de um array JSON (arquivo ou stdin); `--one '{...}'` para um único elemento
`apply [file\|-]`	Patch multi-operação em uma única chamada: `{"create":[...],"update":[{"id":"a","set":{...}}],"delete":["id"]}`
`get <id>` / `delete <id...>`	Lê / remove elementos
`update <id> --set '{...}'`	Atualiza um elemento
`query`	`--type`, `--bbox x0,y0,x1,y1`, `--filter k=v` (chaves aninhadas e tipadas), `--filter-json '{...}'`
`describe`	Resumo da cena legível por IA (texto simples)
`screenshot`	`--out f.png`, `--format png\|svg`, `--no-background` (requer aba do navegador)
`export [--out f.excalidraw] [--format json\|obsidian]` / `import [file\|-] [--replace]`	I/O de arquivos de cena — um caminho de saída `.md` grava o formato `.excalidraw.md` do Obsidian; `import` o lê de volta
`mermaid [file\|-]`	Mermaid → canvas (requer aba do navegador)
`snapshot save\|list\|restore <name>`	Snapshots nomeados
`arrange align\|distribute\|group\|ungroup\|lock\|unlock\|duplicate`	Operações de layout (`--ids a,b,c`, `--to left\|horizontal\|...`)
`share`	Upload criptografado → URL compartilhável do excalidraw.com
`clear --yes`	Limpa o canvas
`install-skill [--dir <skills-root>]`	Instala a skill portátil do agente

Rótulos e vínculos de setas usam o formato amigável ao agente em toda a CLI: "text" em qualquer forma, "startElementId"/"endElementId" em setas — a normalização é automática.

Configurar Clientes MCP

O servidor MCP roda via stdio. Desde a v1.1, a configuração mais simples é npx — sem clone, sem caminhos absolutos, e o canvas inicia automaticamente:

Variáveis de Ambiente

Variável	Descrição	Padrão
`EXPRESS_SERVER_URL`	URL do servidor de canvas	`http://127.0.0.1:3000`
`ENABLE_CANVAS_SYNC`	Habilita sincronização de canvas em tempo real	`true`
`EXCALIDRAW_NO_AUTOSTART`	Defina `1` para desabilitar o início automático do canvas	(não definido)
`EXCALIDRAW_EXPORT_DIR`	Diretório base onde as exportações de arquivos MCP podem gravar	diretório de trabalho atual
`PORT` / `HOST`	Endereço de bind do servidor de canvas	`3000` / `127.0.0.1`

Claude Desktop

Local do arquivo de configuração:

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

Dica: para agentes de codificação, a skill + CLI geralmente supera a configuração MCP — deixe o agente escolher a raiz da skill e execute npx -y mcp-excalidraw-server install-skill --dir <skills-root>.

Local (node) — Nível de usuário (disponível em todos os projetos):

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

Gerenciar servidores:

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

Cursor

Local do arquivo de configuração: .cursor/mcp.json na raiz do seu projeto (ou ~/.cursor/mcp.json para configuração 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

Gerenciar servidores:

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

OpenCode

Local do arquivo de configuração: ~/.config/opencode/opencode.json ou opencode.json no nível do projeto

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

Antigravity (Google)

Local do arquivo de configuração: ~/.gemini/antigravity/mcp_config.json

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

Notas

Rede Docker: Use host.docker.internal para alcançar o servidor de canvas rodando na sua máquina host. No Linux, talvez seja necessário --add-host=host.docker.internal:host-gateway ou usar 172.17.0.1. A imagem Docker MCP define EXCALIDRAW_NO_AUTOSTART=1 (não possui build de frontend) — execute o canvas como um contêiner próprio.
Armazenamento em memória: O servidor de canvas armazena elementos em memória. Reiniciar o servidor limpa todos os elementos — use export / snapshot para persistência.

Ferramentas MCP (26 no total)

Categoria	Ferramentas
CRUD de Elementos	`create_element`, `get_element`, `update_element`, `delete_element`, `query_elements`, `batch_create_elements`, `duplicate_elements`
Layout	`align_elements`, `distribute_elements`, `group_elements`, `ungroup_elements`, `lock_elements`, `unlock_elements`
Consciência de Cena	`describe_scene`, `get_canvas_screenshot`
I/O de Arquivos	`export_scene`, `import_scene`, `export_to_image`, `export_to_excalidraw_url`, `create_from_mermaid`
Gerenciamento de Estado	`clear_canvas`, `snapshot_scene`, `restore_snapshot`
Viewport	`set_viewport`
Guia de Design	`read_diagram_guide`
Recursos	`get_resource`

Esquemas completos são descobertos via tools/list ou em skills/excalidraw-skill/references/cheatsheet.md.

O foco do grupo de viewport pode ajustar o enquadramento com viewportZoomFactor:

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

scrollToElementIds aplica zoom para caber em cada elemento solicitado, enquanto scrollToElementId centraliza um elemento sem alterar o zoom atual. Especifique apenas um modo de viewport por solicitação. viewportZoomFactor aceita valores maiores que 0 e no máximo 1.

Início Rápido (Do Código-Fonte / Docker)

Do código-fonte (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 de canvas Docker:

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

Imagem do servidor MCP: ghcr.io/yctimlin/mcp_excalidraw:latest (stdio; aponte EXPRESS_SERVER_URL para o contêiner do canvas).

Testes

Teste Rápido da 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

Teste Rápido do Canvas (HTTP)

curl http://127.0.0.1:3000/health

Teste de Regressão de Bind Local

npm run test:bind

Testes de Regressão do Canvas no Navegador

Esses testes Chromium compilam o app e iniciam um servidor localhost isolado. Eles cobrem recarga/reconexão de frames, cenas mistas, proteção de sincronização em falha de carregamento, respostas obsoletas, limpeza/exclusão, importações Mermaid e exportação SVG. Eles se recusam a reutilizar um servidor existente; defina CANVAS_TEST_PORT se a porta 51910 estiver ocupada.

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

Teste de Fio MCP Stdio

Aciona dist/index.js com frames JSON-RPC brutos e verifica ambas as eras de protocolo: server/discover, chamadas de ferramentas enviadas sem handshake, recusa de revisões de protocolo não suportadas e envelopes _meta malformados, e o caminho legado initialize.

npm run test:mcp

Teste Rápido MCP (MCP Inspector)

Listar ferramentas:

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

Criar um retâ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 Tela do Frontend (agent-browser)

Se você usa agent-browser para verificações 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

FAQ

Como isso é diferente do MCP oficial do Excalidraw?

O MCP oficial do Excalidraw é um widget de chat: você solicita, ele transmite um diagrama na conversa (o modelo recebe duas ferramentas). Este projeto é uma bancada de trabalho para agentes de codificação: um canvas local persistente com CRUD de elementos em nível de elemento, ferramentas de layout, capturas de tela que o modelo pode ver, snapshots e I/O de arquivos .excalidraw — acionável via CLI, MCP ou REST. Veja a tabela de comparação completa.

Com quais ferramentas de IA ele funciona?

Claude Code, Claude Desktop, Cursor, Codex CLI, OpenCode e Google Antigravity estão documentados abaixo — mas qualquer agente que possa executar comandos de shell pode usar a CLI, qualquer cliente MCP pode usar o servidor MCP, e qualquer outra coisa (LangChain, apps personalizados) pode usar a API REST.

A IA consegue realmente ver o diagrama que desenhou?

Sim — esse é o recurso principal. describe retorna um resumo de texto estruturado (ids, posições, rótulos, conexões) e screenshot retorna um PNG renderizado. Agentes usam ambos para detectar rótulos truncados, sobreposições e roteamento ruim de setas, e então corrigem elemento por elemento.

Preciso de um navegador aberto?

Apenas para recursos dependentes de renderização: capturas de tela, exportação PNG/SVG, controle de viewport e conversão Mermaid (eles renderizam no frontend do Excalidraw). Criar, consultar, atualizar elementos e exportar JSON .excalidraw funcionam sem navegador. A CLI sai com código 4 e informa quando uma aba do navegador é necessária.

Meus diagramas são persistentes?

O canvas é em memória por design (reiniciar = canvas em branco). Persista exportando arquivos .excalidraw no seu repositório (export --out docs/architecture.excalidraw) ou com snapshots nomeados enquanto trabalha. Re-import um arquivo para continuar refinando depois.

Os links de compartilhamento do excalidraw.com são privados?

share criptografa a cena localmente com AES-GCM antes do upload; a chave de descriptografia está apenas no fragmento da URL, que o servidor do excalidraw.com nunca vê. Qualquer pessoa a quem você der o link completo pode visualizar o diagrama.

Ele precisa de chave de API ou serviço em nuvem?

Nenhuma chave de API é necessária. O desenho principal roda localmente sob licença MIT. A única chamada externa é o upload opcional share para excalidraw.com.

Posso usá-lo sem configurar MCP?

Sim — esse é o caminho recomendado para agentes de codificação: npx -y mcp-excalidraw-server install-skill --dir <skills-root> e o agente dirige tudo pela CLI. A configuração MCP só é necessária para clientes de chat como Claude Desktop.

Solução de Problemas

Código de saída 3 da CLI (canvas inacessível): o servidor não está rodando para um comando de inspeção como status, o início automático está desabilitado (EXCALIDRAW_NO_AUTOSTART=1), ou EXPRESS_SERVER_URL aponta para um host não-loopback. Execute start explicitamente ou corrija o env.
Código de saída 4 da CLI (navegador necessário): capturas de tela, exportação de imagens, viewport e conversão Mermaid renderizam no frontend — abra http://127.0.0.1:3000 em um navegador e tente novamente.
Canvas não atualizando: confirme que EXPRESS_SERVER_URL aponta para o servidor de canvas em execução (status mostra a URL em uso).
Atualizações/exclusões falham após criação em lote: certifique-se de estar em um build que inclui a correção de preservação de id em lote (mesclada via PR #34).

Problemas Conhecidos / TODO

Armazenamento persistente: Elementos são armazenados em memória — reiniciar o servidor limpa tudo. Use export / snapshots como solução alternativa.
Exportação de imagens requer navegador: capturas de tela e exportação de imagens dependem do frontend para renderização real. Um modo de renderização headless está planejado.

Contribuições são bem-vindas!

Desenvolvimento

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

Relatos de bugs e pull requests são bem-vindos em GitHub issues. Se este projeto ajudar você, uma ⭐ ajuda outros a encontrá-lo.

Licença

MIT © yctimlin — não afiliado à equipe do Excalidraw. Excalidraw é um projeto próprio sob licença MIT; este toolkit é construído sobre ele com carinho.

Links: pacote npm · GitHub · Issues · Vídeo de demonstração