# excalidraw-mcp

An MCP server that lets your agent add nodes and arrows to an Excalidraw file and read the whole diagram back. Handy when a schema has to change from inside the chat.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: cmd8
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cmd8/excalidraw-mcp
- Updated: 2025-11-29
- HTML: https://affpapa.org/en/nevibecode/mcp/excalidraw-mcp

## What it does

Four tools come with the server. `createNode` drops in a shape with a label and hands back its ID. `createEdge` draws an arrow between two nodes, and you can point at either an ID or the label text. `deleteElement` removes a node or an edge, while `getFullDiagramState` returns a markdown view of the diagram: nodes, relationships, labels, frames and colors.

It runs through `npx`, so Node.js 18.0.0 or newer has to be on the machine. The `-d, --diagram` flag is required at startup and takes the path to a `.excalidraw` file; skip it and the server never comes up. You set that path once in the config, and the agent keeps working against that one file.

Wiring it in is either a single terminal command or a JSON block in your editor's MCP settings. Claude takes `claude mcp add`, Codex takes `codex mcp add`, Gemini CLI takes `gemini mcp add`. Cursor, Windsurf, GitHub Copilot and VS Code expect the server in a config file you edit yourself.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add excalidraw-mcp -- npx -y @cmd8/excalidraw-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add excalidraw-mcp -- npx -y @cmd8/excalidraw-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "excalidraw-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@cmd8/excalidraw-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "excalidraw-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@cmd8/excalidraw-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add excalidraw-mcp npx -y @cmd8/excalidraw-mcp
```

## When to use it
- sketch a service diagram out of nodes and arrows
- add a labeled box to a diagram that already exists
- connect two nodes by label text when the IDs are unknown
- read the current diagram state as markdown
- drop a node or edge you no longer need

## Example prompts
- Add a node called "Queue" to the diagram and connect it to "API"
- Show me the full diagram state in markdown
- Delete the edge between "Client" and "Gateway"

## Similar
- [excalidraw](https://affpapa.org/en/nevibecode/skills/agents365-ai-excalidraw.md) — skill · 4600 installs
- [excalidraw-skill](https://affpapa.org/en/nevibecode/skills/excalidraw-skill.md) — skill · 1500 installs
- [Excalidraw Architect](https://affpapa.org/en/nevibecode/mcp/excalidraw-architect.md) — MCP server · ★ 161
- [excalidraw-diagram-generator](https://affpapa.org/en/nevibecode/skills/excalidraw-diagram-generator.md) — skill · 31639 installs
- [excalidraw-diagram](https://affpapa.org/en/nevibecode/skills/excalidraw-diagram.md) — skill · 8600 installs
- [hand-drawn-diagrams](https://affpapa.org/en/nevibecode/skills/muthuishere-hand-drawn-diagrams.md) — skill · 620 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md