mcp-excalidraw-server

When constructing element JSON for the API or CLI, note these specific requirements:

• Labels: Use "label": {"text": "..."} for shape labels. (Note: This differs from the simplified text field used in some CLI contexts).
• Arrows: Bind arrows using "start": {"id": "..."} and "end": {"id": "..."}.
• Curved Arrows: For smooth curves, use "roundness": {"type": 2} with 3 or more points. For right-angle routing, use "elbowed": true.
• Fonts: fontFamily must be a string (e.g., "1" or "helvetica"). Do not pass a number.
• Points: The points field accepts both [[x,y]] (tuples) and [{x,y}] (objects).

Unlike the official Excalidraw MCP which acts as a chat widget for streaming diagrams into a conversation, this project is designed as a workbench for coding agents.

Key differences include:

• Persistent Local Canvas: Provides a persistent workspace with element-level CRUD (Create, Read, Update, Delete) capabilities.
• Advanced Tooling: Includes layout tools, snapshots, and .excalidraw file I/O.
• Agent Visibility: Agents can use describe to get a structured text summary of the scene and screenshot to receive a rendered PNG, allowing them to visually inspect and fix diagrams.
• Multiple Interfaces: Can be driven via CLI, MCP, or a REST API.

To use the Excalidraw MCP server with Claude Desktop, add the configuration to your claude_desktop_config.json file.

Locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Recommended Configuration (npx):

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

You can add the Excalidraw MCP server to Claude Code using the claude mcp add command.

Recommended (npx):

claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server

Local (node):

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

Docker:

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

Management Commands:

• claude mcp list: List configured servers
• claude mcp remove excalidraw: Remove a server

To give a coding agent the ability to use the Excalidraw toolkit, use the install-skill command. This copies a portable skill directory into the agent's designated skill root, teaching the agent the workflow for layout planning, screenshot verification, and file I/O.

Installation Commands:

• Modern coding agent: npx -y mcp-excalidraw-server install-skill --dir <skills-root>
• Claude Code shortcut: npx -y mcp-excalidraw-server install-skill (installs to ~/.claude/skills)
• Codex shortcut: npx -y mcp-excalidraw-server install-skill --target codex (installs to ~/.codex/skills)

Re-running install-skill performs an in-place upgrade by replacing the target directory.

Add the Excalidraw MCP server to Cursor by editing your .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global) file.

Recommended (npx):

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "mcp-excalidraw-server"]
    }
  }
}

If you are working within an Obsidian vault (any directory containing .obsidian/), use the .excalidraw.md extension to ensure compatibility with the Excalidraw Obsidian plugin.

Using .excalidraw.md allows for block references, vault-wide search, and proper Obsidian Sync support. The CLI handles the conversion to the plugin's native format automatically.

Commands for Obsidian:

• Export to Obsidian format: export --out "$VAULT/path/to/file.excalidraw.md" (or use --format obsidian).
• Import from Obsidian format: import "$VAULT/path/to/file.excalidraw.md" --replace (supports both plain and compressed Drawing blocks).

npx -y mcp-excalidraw-server export --out "$VAULT/diagrams/system-map.excalidraw.md"
npx -y mcp-excalidraw-server import "$VAULT/diagrams/system-map.excalidraw.md" --replace

You can run the Excalidraw CLI using npx or by installing it globally. The CLI commands interact with a running canvas server.

Key Configuration:

• Canvas URL: Controlled by the EXPRESS_SERVER_URL environment variable (defaults to http://127.0.0.1:3000) or via the --url <canvasUrl> flag.
• Auto-start: Any canvas-touching CLI command will automatically attempt to start the server if it is not running. To disable this behavior, set EXCALIDRAW_NO_AUTOSTART=1.
• Exit Codes:
  • 0: Success
  • 1: Error
  • 2: Usage error
  • 3: Canvas unreachable
  • 4: Browser tab required (for certain visual commands)

npx -y mcp-excalidraw-server <command>
# Or after global installation:
excalidraw-canvas <command>

To run the Excalidraw components from source (requires Node >= 18):

1. Install dependencies:

   npm ci

2. Build the project:

   npm run build

3. Run the Canvas Server (Terminal 1):

   PORT=3000 npm run canvas

4. Run the MCP Server (Terminal 2):

   node dist/index.js

5. Use the CLI (Optional):

   node dist/bin.js status