# Excalidraw MCP — Generate Diagrams from Claude Code

> Excalidraw MCP exposes the Excalidraw scene API as MCP server. Claude Code / Cursor draw architecture diagrams, ERDs, flowcharts to a .excalidraw file.

## Install

Merge the JSON below into your `.mcp.json`:

## Quick Use

1. Add the JSON snippet below to your MCP config (Claude Code: `~/.claude/mcp.json`)
2. Restart your MCP host
3. Ask the agent to draw a diagram — it calls the Excalidraw MCP tools

---

## Intro

Excalidraw MCP wraps the Excalidraw scene API as a Model Context Protocol server. Claude Code / Cursor / Codex CLI can call `excalidraw_create_scene`, `excalidraw_add_shape`, `excalidraw_add_arrow` to generate architecture diagrams, ERDs, and flowcharts directly into a `.excalidraw` file. Best for: agents documenting code with diagrams without copy-paste from a separate diagram tool. Works with: Excalidraw 0.17+, any MCP host. Setup time: 3 minutes.

---

### MCP config

```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "excalidraw-mcp"],
      "env": {
        "EXCALIDRAW_OUTPUT_DIR": "./diagrams"
      }
    }
  }
}
```

### Tools exposed

| Tool | Behavior |
|---|---|
| `excalidraw_create_scene` | Start a new `.excalidraw` file |
| `excalidraw_add_rectangle` | Box (x, y, w, h, text, color) |
| `excalidraw_add_ellipse` | Circle/ellipse |
| `excalidraw_add_arrow` | Arrow connecting two shape IDs |
| `excalidraw_add_text` | Free text label |
| `excalidraw_export_png` | Render to PNG (with custom theme) |

### Example prompt to Claude Code

```
> Read the architecture from src/. Generate an Excalidraw diagram showing:
  - Frontend (Nuxt) at top
  - API gateway
  - 3 microservices (auth, payments, notifications)
  - Postgres + Redis at bottom
  - Arrows showing typical request flow
  Save to docs/architecture.excalidraw and export PNG.
```

Claude Code calls the MCP tools step by step, lays out shapes with sensible spacing, and saves both the editable `.excalidraw` and a `.png` preview.

### Open in Excalidraw

```bash
open https://excalidraw.com  # then drag-and-drop the file
# or
excalidraw open ./docs/architecture.excalidraw  # if Excalidraw desktop installed
```

### Use as a CI artifact

Diagrams generated by the MCP server in CI can be attached to PRs as architecture documentation that updates automatically with code changes.

---

### FAQ

**Q: Is Excalidraw MCP official?**
A: Excalidraw the editor is official (excalidraw/excalidraw on GitHub, ~95K stars). The MCP server wrappers are community-built — multiple implementations exist (excalidraw-mcp, excalidraw-mcp-server). They use the official Excalidraw scene format.

**Q: Will the diagram be editable in Excalidraw afterwards?**
A: Yes — the output is a standard `.excalidraw` JSON file. Open it in Excalidraw web (excalidraw.com) or desktop, edit, save. The agent-generated layout is just a starting point.

**Q: Can it draw on top of an existing diagram?**
A: Yes — pass the existing `.excalidraw` file and use `excalidraw_load_scene` first. The agent appends or modifies. Useful for incremental architecture docs.

---

## Source & Thanks

> Built by [Excalidraw](https://github.com/excalidraw) + community MCP servers. Licensed under MIT.
>
> [excalidraw/excalidraw](https://github.com/excalidraw/excalidraw) — ⭐ 95,000+

---

<!-- ZH -->

## 快速使用

1. 把下面的 JSON 加到 MCP 配置（Claude Code 的 `~/.claude/mcp.json`）
2. 重启 MCP 宿主
3. 让 agent 画图，它会调 Excalidraw MCP 工具

---

## 简介

Excalidraw MCP 把 Excalidraw 场景 API 包成 Model Context Protocol server。Claude Code / Cursor / Codex CLI 能调 `excalidraw_create_scene` / `excalidraw_add_shape` / `excalidraw_add_arrow` 直接生成架构图、ERD、流程图到 `.excalidraw` 文件。适合 agent 给代码画图、不想从另一个画图工具复制粘贴的场景。需要 Excalidraw 0.17+ 和任意 MCP 宿主。装机时间 3 分钟。

---

### MCP 配置

```json
{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "excalidraw-mcp"],
      "env": {
        "EXCALIDRAW_OUTPUT_DIR": "./diagrams"
      }
    }
  }
}
```

### 暴露的工具

| 工具 | 行为 |
|---|---|
| `excalidraw_create_scene` | 创建新 `.excalidraw` 文件 |
| `excalidraw_add_rectangle` | 矩形（x、y、w、h、文字、颜色） |
| `excalidraw_add_ellipse` | 圆/椭圆 |
| `excalidraw_add_arrow` | 连接两个 shape ID 的箭头 |
| `excalidraw_add_text` | 自由文本标签 |
| `excalidraw_export_png` | 渲染成 PNG（自定义主题） |

### 给 Claude Code 的 prompt 示例

```
> 读 src/ 的架构。生成 Excalidraw 图：
  - 顶部前端（Nuxt）
  - API 网关
  - 3 个微服务（auth / payments / notifications）
  - 底部 Postgres + Redis
  - 箭头展示典型请求流程
  保存到 docs/architecture.excalidraw，并导出 PNG。
```

Claude Code 一步步调 MCP 工具、按合理间距排布形状、保存可编辑 `.excalidraw` 和 `.png` 预览。

### 在 Excalidraw 里打开

```bash
open https://excalidraw.com  # 拖文件进去
# 或
excalidraw open ./docs/architecture.excalidraw  # 装了桌面版
```

### 当 CI 产物用

CI 里 MCP server 生成的图可以作为 PR 附件作为架构文档，跟着代码自动更新。

---

### FAQ

**Q: Excalidraw MCP 是官方的吗？**
A: Excalidraw 编辑器本身是官方（excalidraw/excalidraw on GitHub，~95K stars）。MCP server 包装是社区做的 —— 有多个实现（excalidraw-mcp / excalidraw-mcp-server）。都用官方 Excalidraw 场景格式。

**Q: 生成的图后续在 Excalidraw 里能编辑吗？**
A: 能 —— 输出是标准 `.excalidraw` JSON 文件。在 Excalidraw 网页（excalidraw.com）或桌面版打开、编辑、保存。agent 生成的布局只是起点。

**Q: 能在已有图上画吗？**
A: 能 —— 传入已有的 `.excalidraw` 文件，先用 `excalidraw_load_scene`。agent 追加或修改。适合增量的架构文档。

---

## 来源与感谢

> Built by [Excalidraw](https://github.com/excalidraw) + community MCP servers. Licensed under MIT.
>
> [excalidraw/excalidraw](https://github.com/excalidraw/excalidraw) — ⭐ 95,000+


---
Source: https://tokrepo.com/en/workflows/excalidraw-mcp-generate-diagrams-from-claude-code
Author: Excalidraw