# Free Enhanced Excalidraw MCP

[English (main)](README.md) · [Tiếng Việt](README.vi.md) · [Benchmark methodology](benchmarks/model-benchmark.md)

A community fork of the [official Excalidraw MCP App](https://github.com/excalidraw/excalidraw-mcp) with local PNG previews, editable exports, layout diagnostics and reusable sketch libraries. It uses the real Excalidraw renderer and needs **no Excalidraw Plus API key**.

This is an unofficial project. Excalidraw and Excalidraw Plus are separate upstream products; their authors do not endorse this fork.

## Text-to-drawing benchmark

One complex text brief, **GPT-6.1 Sol with `max` reasoning**, three fresh tool-calling contexts. Each model run invents its own scene using one provider's drawing tools and guides. No reference image, coordinates or shared scene plan is supplied.

[![The Clockwork Storm Garden: original free, enhanced free and Plus drawn independently from the same text prompt](docs/comparison/storm-garden.png)](docs/comparison/storm-garden.png)

Open the full-size results: [Original free MCP](docs/comparison/model/upstream-free/storm-garden.png) · [Enhanced free MCP](docs/comparison/model/enhanced/storm-garden.png) · [Plus](docs/comparison/model/plus/storm-garden.png).

The brief asks for a cutaway greenhouse with a swirling cloud, winding pipes, a water-cycle feedback route, plants, a gardener and mechanical details. The model may inspect and refine its own drawing under the same budget for every provider.

See the [exact prompt](benchmarks/inputs/storm-garden.prompt.txt), [method and review criteria](benchmarks/model-benchmark.md), [visual observations](benchmarks/visual-review.md), and [results with tool traces](docs/comparison/model). This is one trial per provider, not a statistically reliable quality ranking. The earlier [fixed-plan rendering diagnostics](benchmarks/README.md) test a different question.

## Compare the three options

| Need | Original free MCP | This enhanced fork | Excalidraw Plus API |
|---|---|---|---|
| Free drawing without a Plus API key | Yes | Yes | API key required |
| Interactive MCP App editing | Yes | Yes | Plus workspace tools |
| Local PNG/SVG/`.excalidraw` export through MCP tools | No dedicated export tool in the tested version | Yes | Screenshot and scene-content tools |
| Automatic graph layout | Agent positions elements | `create_diagram` | Graph and Mermaid tools |
| Layout diagnostics through MCP | No dedicated inspector in the tested version | `inspect_diagram` | `check_scene_layout` and write diagnostics |
| Font choice | Tested preview forces Excalifont | Excalifont, Virgil, Nunito, Comic Shanns | API-supported fonts; see its guide |
| Vietnamese handwriting extensions bundled locally | Not provided by the tested version | Excalifont and Virgil extensions | Follow the Plus font guide |
| Reusable editable libraries through MCP | Agent supplies elements | Browse, import and place library items | Separate drawing/workspace API |
| Collections, collaboration and presentation management | Excalidraw sharing | Upstream sharing support | Workspace, collections and slide tools |

Use the original free MCP for the simplest hosted MCP App setup. Use this fork for a local workflow with previews, exports, typography control and diagnostics. Use Plus when its hosted workspace, collections, presentation or other API functions fit your work. The text-to-drawing trial and rendering diagnostics exercise selected tasks; they are not an overall quality ranking.

## Render and font diagnostics

These older tests intentionally replay the same scene through all three providers. They isolate renderer, typography and export behavior; they do not test independent scene generation.

- [Local-first illustration](docs/comparison/local-first.png)
- [Fonts and Vietnamese glyphs](docs/comparison/typography.png)
- [Prompts, source inputs and diagnostic method](benchmarks/README.md)

## Install from source

Requirements:

- Node.js 22 or newer.
- Google Chrome installed on the machine running the MCP server. Native previews and exports launch Chrome headlessly through Playwright.
- pnpm 10.11.0, or `npx` to run the pinned pnpm version below.

```bash
git clone https://github.com/IvanLyVodka11/excalidraw-free-enhanced-mcp.git
cd excalidraw-free-enhanced-mcp
npx --yes pnpm@10.11.0 install --frozen-lockfile
npx --yes pnpm@10.11.0 run build
```

This preview is distributed as source. It has not been published as an npm package; the build prepares the local server in `dist/`.

Add a stdio server to your MCP client's configuration. Replace the example path with the absolute path on your machine:

```json
{
  "mcpServers": {
    "excalidraw-enhanced": {
      "command": "node",
      "args": ["/absolute/path/to/excalidraw-free-enhanced-mcp/dist/index.js", "--stdio"]
    }
  }
}
```

On Windows, forward slashes work in JSON paths, for example `C:/projects/excalidraw-free-enhanced-mcp/dist/index.js`. Restart the client after changing its MCP configuration.

Clients with MCP Apps support can display the interactive editor. Clients that support image tool results can receive PNG previews from the native tools.

Exports default to `Downloads/Excalidraw`. Set `EXCALIDRAW_OUTPUT_DIR` in the server's environment to choose another directory. No `.env` file or Plus API key is needed for this server.

## What is added

- Native `@excalidraw/excalidraw@0.18.0` rendering and editable elements.
- PNG, self-contained SVG with embedded fonts, and `.excalidraw` export.
- Fonts loaded before text measurement; per-label font and size, wrapping, centering and NFC normalization.
- Vietnamese additions to Excalifont and Virgil, preserving their handwriting outlines. These are community extensions, not official font updates.
- Grouped graph layouts in four directions, curved/straight/elbow connectors and real arrow bindings.
- Diagnostics for text overflow, overlaps, rotated geometry and arrows crossing unrelated content.
- A sketch kit plus community computer and office libraries, with `.excalidrawlib` import and reusable placement.

Layout, strokes, colors and fonts are design choices for each request. The comparison fixtures demonstrate specific tasks; they do not prescribe a style for all drawings.

## Tools

The original five tools remain. Six tools are added:

| Tool | Purpose |
|---|---|
| `create_diagram` | Lay out a graph with optional groups and return a native PNG preview |
| `inspect_diagram` | Return affected regions and suggestions for layout problems |
| `export_diagram` | Export PNG, SVG and editable scene files |
| `list_library_items` | Browse bundled or imported libraries |
| `import_library` | Import a local version-1/2 `.excalidrawlib` file or JSON |
| `place_library_item` | Place an editable item while preserving aspect ratio, groups and bindings |

Call `read_me` first. Use `create_diagram` for graph layouts, or `create_view` for free-form work. Review the returned image and diagnostics before exporting. Composite icons share `groupIds`; reserve `customData.allowOverlap` for deliberate overlays.

## Verify and develop

```bash
npx --yes pnpm@10.11.0 run build
npx --yes pnpm@10.11.0 test
```

The tests exercise the real stdio server and browser renderer. They cover fonts, Vietnamese text, wrapping, graph directions/groups, arrow bindings, geometry diagnostics, library transformations and invalid inputs. Generated test files go to the ignored `samples/` directory.

For interactive development:

```bash
npx --yes pnpm@10.11.0 run dev:ui
```

Optional font rebuilding uses Python, fontTools and Brotli; the generated WOFF2 files are already included for normal installation. See `scripts/build-vietnamese-fonts.py`.

## Practical limits

- Google Chrome is a runtime dependency for local rendering.
- The interactive MCP App retains upstream public CDN module/CSS loading. Exported PNG/SVG files are self-contained; this does not make the entire interactive widget an offline application.
- The public Excalidraw website may not have this fork's Vietnamese font extensions when opening an editable file. Keep the PNG/SVG for the exact exported appearance.
- Diagnostics approximate geometry. Curves, freehand shapes and intended overlaps still require visual review.
- This fork does not reproduce Plus account, collaboration, storage or presentation services.

## Credits and licenses

Based on [excalidraw/excalidraw-mcp](https://github.com/excalidraw/excalidraw-mcp), starting at commit [`157aa23`](https://github.com/excalidraw/excalidraw-mcp/commit/157aa23ceb1976008aadc89eb05e3444060f09d6). Built with [Excalidraw](https://github.com/excalidraw/excalidraw), Rough.js, Dagre, the MCP SDK and Playwright.

Code: [MIT](LICENSE). Fonts retain SIL Open Font License 1.1. Community libraries retain their MIT notice. See [third-party notices](THIRD_PARTY_NOTICES.md).