@excalimate/mcp-server

Turn hand-drawn Excalidraw diagrams into keyframe animations

App · Landing Page · Feedback · MCP Server Docs · Report Bug

Draw diagrams with the full Excalidraw editor, then animate elements with opacity fades, position slides, scale effects, rotation, and arrow draw-on animations. Export as MP4, WebM, GIF, or animated SVG. Includes an MCP server so AI agents can create and animate diagrams in real-time.

Demo

https://github.com/user-attachments/assets/77e87c62-0ff4-4a56-aee6-50553b94798c

Related MCP server: excalidraw-mcp

Features

• Full Excalidraw editor — draw, edit, resize, connect arrows, add text

• Progressive V2 creator — Magic Canvas, plain-language Sequence, and Advanced Studio

• Local animation tools — deterministic Auto Animate, presets, templates, and Smart Transitions

• Keyframe animation — opacity, position, scale, rotation, draw progress

• Advanced timeline — collapsible per-element tracks with interpolation lines, clip markers, scrubbing

• Camera animation — pan/zoom keyframes with aspect ratio control

• Unified export — MP4, WebM, GIF, animated SVG, Lottie, and dotLottie

• Hosted player and embeds — compact playback runtime with responsive controls

• E2E encrypted sharing — expiry and revocation with the AES-256-GCM key kept in the URL hash

• MCP server — 35 tools, including all 29 legacy tools and six structured V2 action tools

• Live mode — watch AI changes appear in the editor in real-time via SSE

Quick Start

Try it now — no cloning required:

npx @excalimate/mcp-server

Point your AI tool to http://127.0.0.1:3001/mcp. After it connects, copy the printed preview pairing URL into File → Preferences in app.excalimate.com, then click Live.

Local development

npm install
npm run dev
# → http://localhost:5173

AI Integration (MCP Server)

The MCP server lets AI agents (Copilot, Claude, Cursor, Windsurf) create and animate diagrams for you. Start the server, connect your AI tool, and watch diagrams appear live in app.excalimate.com.

The recommended workflow is action-first: create a scene, then use auto_animate, apply_animation_preset, upsert_action_sequence, or create_camera_move before reaching for raw keyframes. These tools use the same browser-neutral V2 schema and deterministic animation core as the app stack. The MCP server does not host a model or send scene content to an AI service.

npx @excalimate/mcp-server              # default port 3001
npx @excalimate/mcp-server --port 4000  # custom port

Add to .vscode/mcp.json:

{
  "servers": {
    "excalimate": {
      "type": "http",
      "url": "http://localhost:3001/mcp",
    },
  },
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "excalimate": {
      "command": "npx",
      "args": ["@excalimate/mcp-server", "--stdio"]
    }
  }
}

npx @excalimate/mcp-server &
claude mcp add excalimate http://localhost:3001/mcp

Point your MCP client to http://localhost:3001/mcp and start the server with npx @excalimate/mcp-server.

See mcp-server/README.md for the full tool reference and configuration guide.

AI Skills (Optional)

Excalimate ships with 16 specialized skills that teach AI agents how to create specific diagram types (architecture diagrams, flowcharts, sequence diagrams, etc.) with proper animation patterns. Skills dramatically improve output quality.

GitHub Copilot (recommended):

npx skills add https://github.com/excalimate/excalimate

Manual installation (any agent):

Copy the skills/ directory into your project, or point your agent's skill/context configuration to the skill files. Each skill is a standalone SKILL.md file that can be loaded as context.

Available skills: excalimate-core · animated-presentations · animation-patterns · architecture-diagrams · comparison-diagrams · data-pipelines · diagram-theming · er-diagrams · explainer-animations · export-optimization · flowcharts · mind-maps · network-topologies · org-charts · sequence-diagrams · timeline-roadmaps

Usage

V2 creator workflow

1. Draw with the full Excalidraw editor or start from an animated template.

2. Use Magic to preview local Auto Animate, apply a preset, or create a Smart Transition between captured scene states.

3. Use Sequence to reorder actions and adjust plain-language timing such as after or with the previous action.

4. Open Studio for the preserved advanced timeline, custom keyframes, clip range, camera, and per-track controls.

5. Export a video, image, animated SVG, Lottie, or dotLottie, or create an encrypted expiring share link for hosted playback.

Sharing

Share your animation via File → Share. The project is encrypted client-side with AES-256-GCM and uploaded as an opaque blob — the server never sees the encryption key.

Architecture

excalimate/
├── src/                        # React web app (Vite + TypeScript)
│   ├── components/             # UI (Mantine + Tailwind CSS)
│   ├── core/                   # Animation engine, interpolation, playback
│   ├── stores/                 # Zustand state management
│   ├── services/               # Export pipeline, encryption, file I/O
│   └── hooks/                  # MCP live, hotkeys, auto-save
├── mcp-server/                 # MCP server (Node.js + Express)
│   └── src/server/             # Modular tool registrations
├── packages/
│   ├── project-schema/         # Shared V2 project codec and validation
│   ├── animation-core/         # Shared deterministic action compiler/runtime
│   ├── player-runtime/         # Hosted player package, sanitizer, playback
│   └── export-runtime/         # Unified export sampling and workers
├── skills/                     # AI skill definitions (16 skills)
└── docs/                       # Design guidelines, plans

The web app is a static SPA — all rendering, animation, and editing happens in the browser. The MCP server is optional, used only for AI integration and live preview.

Excalimate V2 documentation

• Migration, architecture, limits, rollout, and rollback

• Magic, Sequence, Studio, templates, and transitions

• Hosted player and embedding

• MCP V2 and deprecations

• Security, sharing retention, and deployment

• Accessibility validation matrix

• Export runtime and format fallbacks

Tech Stack

Development

npm run dev          # Start dev server
npm run build        # Production build
npm run test         # Run tests
npm run lint         # ESLint

Privacy-sensitive deployment settings

The privacy notice depends on production configuration as well as source code:

• Configure the landing-page Cloudflare Workers build with root directory landing-page, build command npm run build, and deploy command npx wrangler versions upload --config dist/server/wrangler.json. The Cloudflare adapter generates that server configuration during the build.

• Use only Cloudflare edge/zone aggregate traffic analytics. Do not enable the Cloudflare Web Analytics browser beacon or export request logs for analytics.

• Do not describe or use Cloudflare's IP-derived unique-visitor metric as anonymous. Delete raw/exported Cloudflare reports within 30 days; aggregate trend reports may be retained without a fixed limit.

• Keep PostHog on Cloud EU with IP capture, autocapture, session replay, surveys, product tours, web experiments, and feature flags disabled. Set event retention to no more than 12 months and review the DPA and subprocessors before release.

• Retain the legitimate-interest and ePrivacy assessments for Cloudflare, GitHub's star-count request, and the pinned unpkg dotLottie runtime. Review the DPIA screening, Article 30 record, and any transfer assessment when a data flow changes.

• Obtain legal approval for the deployed notice and account settings. If the GitHub or unpkg request cannot rely on the documented ePrivacy position in a target jurisdiction, self-host/proxy it or gate it before release.

MCP server:

npm install
npm run build --workspace @excalimate/project-schema
npm run build --workspace @excalimate/animation-core
npm run build --workspace @excalimate/mcp-server
cd mcp-server
node dist/index.js              # HTTP mode
node dist/index.js --stdio      # stdio mode
node dist/index.js --port 4000  # custom port

Acknowledgements

This project was inspired by excalidraw-animate by Daishi Kato, which demonstrated that Excalidraw drawings could be brought to life with animations. Thank you for the inspiration!

Built with Excalidraw — the amazing open-source virtual whiteboard.

License

MIT — see LICENSE