Excalidraw Skill
Create and refine Excalidraw diagrams on a live canvas via 26 MCP tools for architecture sketches, user flows, and agent-readable scene descriptions.
Overview
excalidraw-skill is an agent skill most often used in Build (also Validate prototype and Idea research) that controls a local Excalidraw canvas through 26 MCP tools for diagramming and scene-aware iteration.
Install
npx skills add https://github.com/lingzhi227/agent-research-skills --skill excalidraw-skillWhat is this skill?
- 26 MCP tools covering element CRUD, batch create, align/distribute, group/lock, and scene awareness
- Scene tools include describe_scene for AI-readable types, positions, labels, connections, and bounding boxes
- Defaults to EXPRESS_SERVER_URL canvas (http://localhost:3000) with GET /health for local server checks
- Supports iterative refinement: query_elements, duplicate_elements with offset, and full layout operations
- Cheatsheet groups tools into Element CRUD, Layout & Organization, and Scene Awareness sections
- 26 MCP tools documented
- Default canvas base URL: http://localhost:3000 (EXPRESS_SERVER_URL)
- Health endpoint: GET /health
Adoption & trust: 644 installs on skills.sh; 114 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need editable architecture or flow diagrams your coding agent can build and revise programmatically instead of screenshotting a static whiteboard.
Who is it for?
Builders who already run an Excalidraw express server and want MCP-driven diagram CRUD during planning or documentation sprints.
Skip if: Teams that need polished marketing creative in Figma, or users without a local canvas server and MCP tool access.
When should I use this skill?
When you need programmatic Excalidraw element creation, layout, grouping, or scene description against a running canvas server.
What do I get? / Deliverables
You get structured canvas elements, layout operations, and AI-readable scene descriptions you can loop on until the diagram matches your spec.
- Structured diagram on canvas (elements, groups, connections)
- describe_scene narrative for downstream agent steps
- Iteratively updated layouts via align/distribute tools
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Docs is the primary shelf because the skill optimizes diagrams for communication—RFCs, system maps, and iteratively described scenes—not production UI code. Excalidraw output supports technical documentation and planning artifacts solo builders attach to repos, specs, and agent sessions.
Where it fits
Sketch a competitor capability map with grouped elements before committing to a feature scope.
Lay out a click path with arrows and labels, then duplicate_elements to explore layout variants.
Maintain a living architecture diagram updated via update_element and query_elements during refactors.
Produce an AI-readable describe_scene summary to hand off to an implementation-planning skill.
How it compares
An MCP-integrated diagram driver—not a generative image skill or hand-drawn asset pack.
Common Questions / FAQ
Who is excalidraw-skill for?
Solo developers and indie teams using Claude Code, Cursor, or similar agents who document systems with Excalidraw and want tool-callable canvas control.
When should I use excalidraw-skill?
In Idea research for competitor or system maps, Validate prototype for user flows, and Build docs or pm when you need align/distribute layouts and describe_scene for the next implementation step.
Is excalidraw-skill safe to install?
It assumes a local or configured canvas URL and MCP access; review the Security Audits panel on this page and only point EXPRESS_SERVER_URL at servers you trust.
SKILL.md
READMESKILL.md - Excalidraw Skill
# Excalidraw Skill Cheatsheet ## Defaults - Canvas base URL: `EXPRESS_SERVER_URL` (default `http://localhost:3000`) - Canvas health: `GET /health` ## MCP Tools (26 total) ### Element CRUD | Tool | Description | Required params | |------|-------------|-----------------| | `create_element` | Create shape/text/arrow/line | `type`, `x`, `y` | | `get_element` | Get single element by ID | `id` | | `update_element` | Update element properties | `id` | | `delete_element` | Delete element | `id` | | `query_elements` | Query by type/filters | (optional) `type`, `filter` | | `batch_create_elements` | Create many at once | `elements[]` | | `duplicate_elements` | Clone with offset | `elementIds[]`, (optional) `offsetX`, `offsetY` | ### Layout & Organization | Tool | Description | Required params | |------|-------------|-----------------| | `align_elements` | Align to left/center/right/top/middle/bottom | `elementIds[]`, `alignment` | | `distribute_elements` | Even spacing horizontal/vertical | `elementIds[]`, `direction` | | `group_elements` | Group elements | `elementIds[]` | | `ungroup_elements` | Ungroup | `groupId` | | `lock_elements` | Lock elements | `elementIds[]` | | `unlock_elements` | Unlock elements | `elementIds[]` | ### Scene Awareness (Iterative Refinement) | Tool | Description | Required params | |------|-------------|-----------------| | `describe_scene` | AI-readable scene description (types, positions, labels, connections, bounding box) | (none) | | `get_canvas_screenshot` | Returns PNG image of canvas for visual verification | (optional) `background` | | `get_resource` | Get scene/library/theme/elements | `resource` | ### File I/O & Export | Tool | Description | Required params | |------|-------------|-----------------| | `export_scene` | Export to .excalidraw JSON | (optional) `filePath` | | `import_scene` | Import from .excalidraw JSON | `mode` ("replace"\|"merge"), `filePath` or `data` | | `export_to_image` | Export to PNG/SVG (needs browser) | `format` ("png"\|"svg"), (optional) `filePath`, `background` | | `export_to_excalidraw_url` | Upload & get shareable excalidraw.com URL | (none) | ### State Management | Tool | Description | Required params | |------|-------------|-----------------| | `clear_canvas` | Remove all elements | (none) | | `snapshot_scene` | Save named snapshot | `name` | | `restore_snapshot` | Restore from snapshot | `name` | ### Viewport & Camera | Tool | Description | Required params | |------|-------------|-----------------| | `set_viewport` | Control camera: zoom-to-fit, center on element, manual zoom/scroll (needs browser) | (optional) `scrollToContent`, `scrollToElementId`, `zoom`, `offsetX`, `offsetY` | ### Design Guide | Tool | Description | Required params | |------|-------------|-----------------| | `read_diagram_guide` | Get design best practices (colors, sizing, layout, anti-patterns) | (none) | ### Conversion | Tool | Description | Required params | |------|-------------|-----------------| | `create_from_mermaid` | Mermaid diagram to Excalidraw | `mermaidDiagram` | Notes: - **MCP tools**: Set `text` field on shapes to label them (auto-converts to `label.text`). Use `startElementId`/`endElementId` on arrows. - **REST API**: Use `"label": {"text": "..."}` for shape labels. Use `"start": {"id": "..."}` / `"end": {"id": "..."}` for arrow binding. (Different format from MCP!) - `fontFamily` must be a string (e.g. `"1"`) or omit it entirely — do NOT pass a number. - `points` accepts both `[[x,y]]` tuples and `[{x,y}]` objects. - **Curved arrows**: Use `"roundness": {"type": 2}` with 3+ points for smooth curves. Use `"elbowed": true` for right-angle routing. - Prefer creating shapes first, then arrows, then alignment/grouping. ## Canvas REST API (HTTP) ### Elements | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/api/elements` | List all elements | | `GET` | `/api/elements/:id` | Get element by ID | | `POST` | `/api/elements` | Create e