Excalidraw

Excalidraw MCP

Route before drawing. Excalidraw has two complementary MCP surfaces:

• Excalidraw MCP App: render an interactive canvas inline in an MCP Apps host.
• Excalidraw+ MCP: persist and administer scenes, collections, and workspace data.

Use both when the user wants an inline canvas and a durable Excalidraw+ scene.

Workflow

1. Classify the request:
   • Inline or interactive in chat: use the MCP App.
   • Durable workspace scene, collection, or administration: use Excalidraw+.
   • Both: persist with Excalidraw+, then pass the scene elements to the MCP App.
   • Installation, missing tools, or authentication: read references/install.md and references/tools.md.
2. Discover the live tools. Both integrations are evolving; do not assume a remembered inventory is current.
3. Load the server's format contract before the first content write:
   • MCP App: call read_me before create_view.
   • Excalidraw+: call read_excalidraw_format before edit_scene_content.
4. Choose the visual structure before writing elements: wireframe, workflow, swimlane, sequence, architecture, state machine, timeline, hierarchy, or presentation.
5. Create or edit with valid Excalidraw elements. Bind shape-to-shape arrows explicitly and use shape labels for shape-owned text.
6. Verify the result visually:
   • MCP App: inspect the embedded canvas.
   • Excalidraw+: use take_screenshot for agent QA, then report the scene URL.
7. Finish only when the requested surface exists, is readable, and is accessible in the requested location.

For artifact-specific patterns and the bridge workflow, read references/workflows.md.

Hard Rules

• Do not substitute a browser screenshot when the user requested an inline MCP App. Invoke create_view.
• Treat screenshots as QA evidence, not as the interactive deliverable.
• Do not confuse the Plus API endpoint with the MCP App endpoint.
• Name configured servers by role, such as excalidraw-app and excalidraw-plus; avoid an ambiguous single excalidraw entry.
• Never claim every Plus tool is installed until live discovery confirms it. Key route permissions and workspace role filter the tool list.
• Keep personal and workspace keys separate. Do not print, commit, or embed API keys when an environment-backed header is supported.
• Reconnect or restart the MCP host after configuration changes before judging the installation.
• Prefer search_scene_content over get_scene_content for targeted reads. Load the full scene only when a bridge, export, or ID-sensitive edit requires it.
• Do not delete scenes, collections, users, invites, or existing elements unless the user explicitly requested that destructive action.

Installation Gate

For installation or repair:

1. Select the surface or combination in references/install.md.
2. Configure credentials without exposing them.
3. Restart or reconnect the client.
4. Run scripts/verify-excalidraw-mcp.sh.
5. Compare the live inventory with references/tools.md.

Installation is complete only when the required endpoint responds, the expected tools are discoverable, and the MCP App exposes a valid ui://excalidraw/mcp-app.html resource when inline rendering is required.

Sources

Read references/sources.md when installing, debugging, or making claims about current tool names, permissions, transports, or client support.