---
title: "Excalidraw MCP Server: A Live Canvas Your Agent Can Draw On"
url: "https://mcpshelf.co/servers/excalidraw"
description: "Give an agent a live Excalidraw canvas: it draws diagrams element by element, screenshots its own work, fixes the layout and exports .excalidraw files."
updated: "2026-10-27"
site: "MCP Shelf"
---

# Excalidraw MCP

> A live Excalidraw canvas that an agent draws on, looks at and tidies up.

## At a glance

This community project by yctimlin runs a local Excalidraw canvas and gives the model fine control over it: create, change, group, align and delete individual shapes, then describe the scene or take a screenshot to see what it drew. That loop lets an agent fix overlapping boxes and clipped labels instead of handing you its first attempt.

Finished diagrams can be saved as .excalidraw files (or Obsidian Excalidraw notes) to commit with your code, exported as PNG or SVG, or shared as an encrypted excalidraw.com link. It needs no account or key. It is separate from the official Excalidraw MCP, which draws one diagram inside the chat.

|  |  |
| --- | --- |
| Made by | yctimlin and contributors (community project) |
| GitHub | https://github.com/yctimlin/mcp_excalidraw |
| Licence | MIT |
| npm package | [mcp-excalidraw-server](https://www.npmjs.com/package/mcp-excalidraw-server) 2.1.2 (4 Oct 2026) |
| GitHub stars | 2.6K |
| Last commit | 22 Oct 2026 |
| Tools | 26 |
| Runs on | Your computer |
| Install check | Started in our test |
| Category | [Design, 3D and games](https://mcpshelf.co/categories/design-and-3d) |

**Our check:** We ran this exact config on 27 Oct 2026: it started and answered with 26 tools. The shared database added "start" to the command, which only starts the canvas server. The MCP server runs with no extra argument.

## Tools

We listed 26 tools on 27 Oct 2026. 7 only read; the rest can change things or run commands.

| Tool | Kind | What it is for |
| --- | --- | --- |
| `create_element` | changes | Adds one shape, text or arrow. Arrows can be bound to two shapes. |
| `update_element` | changes | Changes an element's position, size, colours or text. |
| `delete_element` | changes | Removes an element. |
| `query_elements` | reads | Finds elements by type, property or area of the canvas. |
| `get_resource` | reads | Reads a canvas resource, such as the scene or the library. |
| `group_elements` | changes | Groups elements together. |
| `ungroup_elements` | changes | Breaks a group apart. |
| `align_elements` | changes | Lines elements up on one edge or centre. |
| `distribute_elements` | changes | Spaces elements evenly. |
| `lock_elements` | changes | Locks elements so they cannot be moved. |
| `unlock_elements` | changes | Unlocks them again. |
| `create_from_mermaid` | changes | Converts Mermaid text into Excalidraw elements. Needs the canvas open in a browser. |
| `batch_create_elements` | changes | Adds many elements in one call, with custom IDs so arrows can refer to them. |
| `get_element` | reads | Returns one element by ID. |
| `clear_canvas` | changes | Deletes everything on the canvas. |
| `export_scene` | changes | Saves the canvas as .excalidraw JSON, or as an Obsidian Excalidraw note. |
| `import_scene` | changes | Loads a .excalidraw or .excalidraw.md file, or raw JSON. |
| `export_to_image` | changes | Exports the canvas as PNG or SVG. |
| `duplicate_elements` | changes | Copies elements with an offset. |
| `snapshot_scene` | reads | Saves a named snapshot of the canvas. |
| `restore_snapshot` | changes | Restores a named snapshot. |
| `describe_scene` | reads | Describes everything on the canvas in text: shapes, positions, labels and connections. |
| `get_canvas_screenshot` | reads | Renders the canvas to an image so the model can see its work. |
| `read_diagram_guide` | reads | Hands the model a guide to colours, sizes and layouts for clean diagrams. |
| `export_to_excalidraw_url` | changes | Uploads an encrypted copy and returns a shareable excalidraw.com link. |
| `set_viewport` | changes | Zooms and scrolls the canvas view. Needs the canvas open in a browser. |

### How clearly it describes its tools

26 of 26 tools have a description and 0 of 26 say whether they change things. The tool list takes at least ~1,300 tokens of context. No tool says whether it only reads or can change things, so your client treats them all alike: keep approvals on.

## Set it up

### Claude Desktop

Where: claude_desktop_config.json (Settings → Developer → Edit Config)

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

### Claude Code

Where: Your terminal, in the project folder

```bash
claude mcp add-json excalidraw '{"command":"npx","args":["-y","mcp-excalidraw-server"]}'
```

### Cursor

Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

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

### VS Code

Where: .vscode/mcp.json in your project

```json
{
  "servers": {
    "excalidraw": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-excalidraw-server"
      ]
    }
  }
}
```

### Windsurf

Where: ~/.codeium/windsurf/mcp_config.json

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

### ChatGPT

Where: Not supported

ChatGPT only connects to remote servers by URL. This one runs on your computer, so use Claude, Cursor or VS Code.

The canvas starts on its own at http://127.0.0.1:3000; open it to watch. Set EXCALIDRAW_DATA_DIR in env to keep the canvas between restarts, and EXCALIDRAW_EXPORT_DIR to choose where files are written.

## Settings

| Setting | Kind | Required | What it does |
| --- | --- | --- | --- |
| `EXPRESS_SERVER_URL` | env | no | Where the canvas server runs. Example: `http://127.0.0.1:3000` |
| `EXCALIDRAW_NO_AUTOSTART` | env | no | Set to 1 to stop the server from starting the canvas itself. Example: `1` |
| `EXCALIDRAW_EXPORT_DIR` | env | no | The folder exports may be written to. Defaults to the working directory. |
| `EXCALIDRAW_DATA_DIR` | env | no | A private folder that keeps the canvas, images and snapshots across restarts. Without it the canvas lives in memory. |
| `PORT / HOST` | env | no | Where the canvas server listens. Defaults to 3000 on 127.0.0.1. Example: `3000` |
| `EXCALIDRAW_SHARE_UPLOAD_URL` | env | no | Sends share uploads to your own Excalidraw storage backend instead of excalidraw.com. Pair it with EXCALIDRAW_SHARE_BASE_URL. |

## What it can touch

**It can read**

- The local canvas
- .excalidraw files you import

**It can change**

- The local canvas
- Files written under the export folder
- An encrypted upload to excalidraw.com, only when you share

**Safer setup:** Leave HOST at 127.0.0.1: the canvas API has no login, so anyone who can reach it can change the canvas.

## Before you start

- Node.js 20 or newer

## Good for

- Architecture and flow diagrams that live in the repository
- Turning Mermaid text into an editable Excalidraw diagram
- Diagrams the agent checks and corrects before showing you

## If it does not work

**Mermaid conversion or set_viewport fails**
Those two need the canvas page open. Open http://127.0.0.1:3000 in a browser and try again.

**The canvas is blank after a restart**
It lives in memory by default. Set EXCALIDRAW_DATA_DIR, or export to an .excalidraw file before stopping.

**Chinese, Japanese or emoji text shows as boxes in screenshots**
The bundled fonts only cover Latin scripts. Install a CJK font on the machine running the canvas.

**Nothing updates on the canvas**
Check that EXPRESS_SERVER_URL points at the running canvas and that nothing else is using port 3000.

## Similar servers

| Server | Tools | Runs on | Stars |
| --- | --- | --- | --- |
| [MCP Unity](https://mcpshelf.co/servers/mcp-unity) | 34 | Your computer | 2K |
| [Draw.io MCP Server (lgazo)](https://mcpshelf.co/servers/drawio-lgazo) | 30 | Your computer | 1.5K |
| [Blender MCP](https://mcpshelf.co/servers/blender) | 9 | Your computer | 32.4K |
| [Framelink Figma MCP](https://mcpshelf.co/servers/framelink-figma) | 2 | Your computer | 16.1K |

## Questions

### Is this the official Excalidraw MCP?

No. Excalidraw's official server draws one diagram inside the chat. This one gives an agent a full local canvas to edit, inspect and export.

### Does it need an account or key?

No. Everything runs locally; the canvas page loads its fonts from a CDN.

### Are share links private?

The scene is encrypted before upload and the key stays in the link, so only people with the full link can open it.

### Can it work without MCP?

Yes. The same package has a command line and a REST API, and an agent skill for coding agents.

Full docs on GitHub: https://github.com/yctimlin/mcp_excalidraw

---

From [MCP Shelf](https://mcpshelf.co/): A short shelf of MCP servers that are worth installing. Index for agents: https://mcpshelf.co/llms.txt