rabiskko-mcp

MCP server that lets an AI (such as Claude Desktop) draw into the running Rabiskko app.

How it works

Claude Desktop  <--stdio-->  rabiskko-mcp  <--WebSocket ws://127.0.0.1:47600-->  Rabiskko app (editor open)
                             (MCP server +                                       └─ WS client -> executeSceneCommand -> editor
                              WS bridge)

• rabiskko-mcp is a standalone Node process. Claude Desktop launches it and talks to it over stdio (the MCP transport).
• The MCP server exposes drawing tools (one per scene command). It cannot touch the browser directly, so it is also a local WebSocket server.
• The running Rabiskko app connects out to that WS server whenever an editor is open. When a tool is called, the command is forwarded to the app, executed against the live Excalidraw canvas, and the result is returned to the AI.
• If no Rabiskko drawing is open, tools return a clear error: "Nenhum desenho aberto no Rabiskko. Abra um desenho no app para a IA poder desenhar."

You must have the Rabiskko app open with a drawing for the tools to work.

Tools

| Tool | Input | Returns | | ----------------- | ------------------------------------------ | --------------------------- | | create_elements | skeleton: Excalidraw element skeletons | ok | | read_scene | – | current elements as JSON | | update_elements | elements: full element objects (by id) | ok | | delete_elements | ids: element ids | ok | | export_png | scale? (0.5–3) | PNG image content | | export_svg | – | SVG markup (base64) as text |

create_elements accepts Excalidraw's element skeleton format: an array of objects like { type: "rectangle", x, y, width, height, strokeColor, ... }. Supported types: rectangle, ellipse, diamond, text, arrow, line, frame. Arrows can bind to shapes via start / end. The tool description tells the AI all of this so it produces valid skeletons.

Testar agora, sem publicar (npm link)

Você pode testar o pacote localmente, do jeito que ele vai rodar depois de publicado, sem precisar publicar nada:

cd apps/mcp
npm run build
npm link

Isso compila para dist/ e cria um link global chamado rabiskko-mcp. Depois, configure o Claude Desktop apontando só para o comando (sem caminho absoluto):

{
  "mcpServers": {
    "rabiskko": {
      "command": "rabiskko-mcp"
    }
  }
}

Reinicie o Claude Desktop. Abra o app Rabiskko com um desenho antes de pedir para a IA desenhar — o bridge WS escuta em ws://127.0.0.1:47600 e as tools só funcionam com um editor aberto e conectado.

Para desfazer o link mais tarde: npm unlink -g rabiskko-mcp.

Publicar (quem publica é o usuário)

O publish exige aprovação por 2FA no navegador, então quem roda isso é você, não o assistente:

cd apps/mcp
npm run build
npm publish

(Se em algum momento o nome rabiskko-mcp estiver ocupado e o pacote precisar voltar a ser escopado como @rabiskko/mcp, use npm publish --access public.)

O terminal vai abrir uma aprovação de login/2FA no navegador — aprove por lá.

Depois de publicado

Configuração do Claude Desktop passa a usar npx, sem precisar instalar nada manualmente:

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

O Claude Desktop chama npx -y rabiskko-mcp sempre que precisa do servidor; o npx baixa (e cacheia) a versão publicada automaticamente.

Edite o config do Claude Desktop em:

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

Reinicie o Claude Desktop depois de editar. Depois, abra um desenho no app Rabiskko e peça para o Claude desenhar.

Desenvolvimento local (dentro do monorepo)

npm run dev -w apps/mcp     # tsx watch, sem build
npm run build -w apps/mcp   # compila para dist/
npm run start -w apps/mcp   # roda o compilado
npm run typecheck -w apps/mcp

Ao rodar, o servidor imprime (em stderr) que o bridge está escutando em ws://127.0.0.1:47600. Ele funciona normalmente sem nenhum app conectado — as tools apenas retornam erro até que um desenho esteja aberto.

Environment

• RABISKKO_MCP_PORT — porta do bridge (padrão 47600). Se você mudar, o app Rabiskko precisa usar a mesma porta (VITE_RABISKKO_MCP_PORT no app web).

Segurança — localhost only

O bridge WebSocket escuta somente em 127.0.0.1 (loopback). Não tem autenticação porque nunca sai da máquina: a única função dele é ligar uma IA local ao app Rabiskko local, na mesma máquina.

• Não é alcançável por outras máquinas nem pela rede.
• Não mude o host de bind para 0.0.0.0 nem exponha a porta — isso criaria um canal de "desenhar no meu app" sem autenticação para qualquer um que alcançar a porta.

Isso é um recurso local/dev por design. Se o Rabiskko algum dia precisar de IA desenhando remotamente, isso vai exigir um transporte autenticado de verdade, não esse bridge.