excalidraw-agent-local-kit

Local-first Excalidraw MCP workflow kit for Codex and Claude Code, with scene-file editing and practical fixes for missing-text share links.

What This Repo Is

This repo is a thin integration layer around the upstream excalidraw/excalidraw-mcp server.

It does not re-publish the upstream server code as a new product. Instead, it packages the parts that are usually missing in real usage:

• a local-first scene workflow
• a reusable agent skill
• local scene templates
• online Claude browser playbooks
• practical guidance for the "share link has no text" pitfall

What Problem It Solves

Most Excalidraw MCP demos stop at "the tool connected". Real usage usually needs more:

• keep a local scene file as the source of truth
• let Codex and Claude Code use the same local MCP server
• avoid treating online share links as the source of truth
• debug cases where the editor shows text but the final share page loses it

Requirements

Quick Start

1. Install upstream Excalidraw MCP

git clone https://github.com/excalidraw/excalidraw-mcp.git "$HOME/auto-skills/excalidraw-mcp"
cd "$HOME/auto-skills/excalidraw-mcp"
pnpm install
pnpm build

2. Configure Codex

Add this to ~/.codex/config.toml:

[mcp_servers.excalidraw]
command = "node"
args = ["/Users/you/auto-skills/excalidraw-mcp/dist/index.js", "--stdio"]

[mcp_servers.excalidraw_remote]
url = "https://mcp.excalidraw.com"

Recommendation:

• use excalidraw as the local default
• keep excalidraw_remote only as a fallback

3. Configure Claude Code

Add the same local server to Claude Code:

claude mcp add excalidraw -- node "$HOME/auto-skills/excalidraw-mcp/dist/index.js" --stdio
claude mcp add excalidraw_remote https://mcp.excalidraw.com

4. Install this skill via symlink

./scripts/install_symlinks.sh

This will create:

• ~/.claude/skills/excalidraw-agent-local-kit
• ~/.codex/skills/excalidraw-agent-local-kit

Both symlinks will point to this repo.

Workflow

Two modes, depending on what the user needs:

Local-first mode (default)

1. Read or create a local *.elements.json scene file.
2. Patch or extend the elements array.
3. Save *.elements.json as the truth source.
4. Run node scripts/export_native_scene.js <scene.elements.json> to generate a native .excalidraw file.
5. User opens the .excalidraw file in excalidraw.com.

Online-share mode

1. Complete local-first steps 1–4.
2. Call mcp export_to_excalidraw to upload and get a shareable link.
3. Verify text is visible on the final share page.

See the workflow diagram: examples/local-scenes/v030_workflow_test.excalidraw — open it in excalidraw.com to view.

File Formats

This kit intentionally uses a lightweight local scene format:

• local truth source: *.elements.json
• native Excalidraw import file: *.excalidraw

Important:

• *.elements.json is for the MCP/local workflow
• it is not the native file format that excalidraw.com accepts via upload/open
• if you upload a local *.elements.json file directly to excalidraw.com, Excalidraw will reject it as an invalid file

To generate a native .excalidraw file from a local scene:

node scripts/export_native_scene.js path/to/scene.elements.json

This writes path/to/scene.excalidraw, strips MCP-only pseudo-elements such as cameraUpdate, and converts shorthand MCP elements into native Excalidraw elements with proper text metrics.

The export helper uses Bun to run Excalidraw's browser-side conversion logic locally, so bun must be available on PATH.

Share-Link Text Pitfall

The most common failure mode is:

• text appears in the editor
• the final share link opens without text

This kit uses a stricter rule:

• critical labels should be real text elements
• final success means the share page visibly contains text
• never stop at "export succeeded"

See:

• references/troubleshooting.md
• prompts/online-claude-browser-playbook.md

Scene Templates

Starter templates live in examples/local-scenes:

• branching_asset_pipeline.elements.json
• independent_longform_flow.elements.json

These are generic workflow examples with no business-specific content.

File Structure

excalidraw-agent-local-kit/
├── SKILL.md
├── README.md
├── CHANGELOG.md
├── docs/
│   └── v0.3.0-iteration-plan.md
├── scripts/
│   ├── export_native_scene.js
│   ├── export_native_scene_impl.mjs
│   ├── install_symlinks.sh
│   └── preflight.sh
├── prompts/
│   └── online-claude-browser-playbook.md
├── references/
│   ├── troubleshooting.md
│   └── upstream-attribution.md
└── examples/
    └── local-scenes/
        ├── README.md
        ├── branching_asset_pipeline.elements.json
        ├── independent_longform_flow.elements.json
        └── v030_workflow_test.excalidraw

License

MIT

Attribution

This repo depends on the upstream Excalidraw MCP project:

• https://github.com/excalidraw/excalidraw-mcp

The upstream server remains upstream work. This repo only open-sources the local workflow, scene-file practices, and agent-facing integration layer.