@lifeng688/excalidraw-mcp

An MCP server for creating, editing, reading, and exporting Excalidraw scenes through AI assistants.

This MCP lets Claude Desktop, Claude Code, Cursor, and other MCP clients generate .excalidraw whiteboard diagrams from natural language — flowcharts, architecture diagrams, project roadmaps, Markdown-to-diagram conversions, README illustrations, and more.

Features

• Create and read Excalidraw scenes
• Add basic elements:
  • rectangle
  • diamond
  • ellipse
  • text
  • arrow
• Connect elements
• Update and delete elements
• List workspace scenes
• Export scenes to JSON
• Generate flowcharts from ordered steps
• Generate architecture diagrams from nodes and edges
• Convert Markdown headings and lists into Excalidraw scenes
• Workspace-based file safety
• Path traversal protection
• Consistent response format

Installation

Via npx (after publish)

npx @lifeng688/excalidraw-mcp

Local development (before publish)

git clone https://github.com/guanweiqiang/excalidraw-mcp.git
cd excalidraw-mcp
npm install
npm run build
npm start

Configuration

Set environment variables to control behavior:

EXCALIDRAW_WORKSPACE_DIR=E:/Excalidraw/Workspace
EXCALIDRAW_AUTO_BACKUP=true
EXCALIDRAW_AUDIT_LOG=true
EXCALIDRAW_MAX_ELEMENTS=300

| Variable | Default | Description | |----------|---------|-------------| | EXCALIDRAW_WORKSPACE_DIR | ./data/scenes | Base directory for all .excalidraw files. All file operations are confined to this path. | | EXCALIDRAW_AUTO_BACKUP | true | Automatically back up files before modifying them. | | EXCALIDRAW_AUDIT_LOG | true | Log every tool call to logs/audit.log. | | EXCALIDRAW_MAX_ELEMENTS | 300 | Maximum number of elements allowed in a single scene. |

Claude Desktop / Claude Code Configuration

npx way

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["@lifeng688/excalidraw-mcp"],
      "env": {
        "EXCALIDRAW_WORKSPACE_DIR": "E:/Excalidraw/Workspace",
        "EXCALIDRAW_AUTO_BACKUP": "true",
        "EXCALIDRAW_AUDIT_LOG": "true",
        "EXCALIDRAW_MAX_ELEMENTS": "300"
      }
    }
  }
}

Local development way

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["E:/test/excalidraw-mcp/dist/index.js"],
      "env": {
        "EXCALIDRAW_WORKSPACE_DIR": "E:/Excalidraw/TestWorkspace",
        "EXCALIDRAW_AUTO_BACKUP": "true",
        "EXCALIDRAW_AUDIT_LOG": "true",
        "EXCALIDRAW_MAX_ELEMENTS": "300"
      }
    }
  }
}

Tools

File Management

| Tool | Description | |------|-------------| | create_scene | Create a new blank Excalidraw scene | | read_scene | Read an existing .excalidraw or .json scene | | list_scenes | List all scenes under the configured workspace | | export_to_json | Export a scene to a standard JSON file |

Element Creation

| Tool | Description | |------|-------------| | add_rectangle | Add a rectangle, optionally with text | | add_diamond | Add a diamond shape, optionally with text | | add_ellipse | Add an ellipse shape, optionally with text | | add_text | Add a standalone text element | | add_arrow | Add an arrow between coordinates | | connect_elements | Connect two existing elements with an auto-calculated arrow |

Editing

| Tool | Description | |------|-------------| | update_element | Update an existing element's properties | | delete_element | Delete (soft-delete) an element |

Advanced Generation

| Tool | Description | |------|-------------| | create_flowchart | Generate a flowchart from ordered step labels | | create_architecture_diagram | Generate an architecture diagram from nodes and edges | | markdown_to_scene | Convert Markdown headings and lists into an Excalidraw scene |

Example Prompts

Natural-language prompts that work with this MCP:

Example 1: Flowchart

Create a flowchart for publishing an npm package, including writing README, implementing features, running tests, fixing bugs, publishing, and writing release notes. Save it as npm-publish-flow.excalidraw.

Example 2: Architecture Diagram

Create an architecture diagram for an e-commerce system with frontend, admin panel, API gateway, user service, order service, payment service, inventory service, database, Redis, and message queue.

Example 3: Markdown to Diagram

Convert this Markdown roadmap into an Excalidraw diagram and save it as project-roadmap.excalidraw.

Example 4: Element Operations

Add a rectangle titled "API Gateway", connect it to "User Service", and export the scene as JSON.

Security

• All file operations are restricted to EXCALIDRAW_WORKSPACE_DIR
• Path traversal (e.g. ../) is rejected
• Unsupported file extensions are rejected
• Write operations cannot escape the workspace
• All inputs are validated with Zod schemas before execution
• Only point this server at a workspace directory you trust

Current Limitations

• Auto-layout is still basic (vertical / horizontal linear)
• Complex diagrams may need manual adjustment in Excalidraw
• Arrow routing is simple (straight lines, no edge detection)
• Visual style presets are limited
• This version focuses on safe, structured scene generation first

Roadmap

See docs/roadmap.md.

• v0.1.x — Core tooling and safety (current)
• v0.2.x — Layout and visual quality
• v0.3.x — Templates and higher-level diagram types
• v1.0.0 — Stable public release

Development

npm install
npm run build
npm start
npm run inspect

This project uses MCP JSON Tester (run-mcp-json-test.mjs) for external integration testing.

Testing

Test coverage includes:

• Create / read / list scenes
• Add / update / delete elements
• Connect elements
• Export JSON
• Generate flowcharts
• Generate architecture diagrams
• Convert Markdown to scenes
• Validate path safety
• Validate invalid extensions
• Validate missing / empty arguments
• Validate Chinese text and nested directories

Troubleshooting

MCP server does not start

• Run npm run build to compile TypeScript
• Check that dist/index.js exists
• Verify Node.js version is >= 18

Files are not created

• Check that EXCALIDRAW_WORKSPACE_DIR points to a valid directory
• Make sure the workspace directory exists or can be created
• Ensure output paths do not attempt to escape the workspace

"Path outside workspace" error

The server restricts all file operations to EXCALIDRAW_WORKSPACE_DIR. Paths containing .. or absolute paths outside the workspace will be rejected. Use relative paths within the workspace.

Generated diagrams look messy

The current version has basic auto-layout. For complex diagrams, you can refine the result in the Excalidraw editor directly. Layout and visual quality improvements are planned for v0.2.0.

License

MIT

Note: A LICENSE file is required for npm publication. Please create one before releasing.