Mcp Obsidian Excalidraw

MCP Obsidian Excalidraw

Let a large language model create and edit Excalidraw drawings inside Obsidian, live, through the Model Context Protocol (MCP).

Ask your assistant "draw a flowchart of the login process" and watch the boxes, arrows and labels appear on the open Excalidraw board — created, styled, connected and rearranged by the model.

---

How it works

The project has two parts that talk to each other:

 LLM client                server.js                 Obsidian plugin            Excalidraw
(Claude Desktop /   ──MCP──▶  (MCP server)  ──HTTP──▶  "MCP Obsidian        ──▶  board on screen
 Claude Code / Qwen)  stdio                :14790      Excalidraw" bridge)        (ExcalidrawAutomate)

1. server.js — an MCP server. It declares the drawing tools to the LLM

client and forwards each call over HTTP to the Obsidian plugin. It contains no drawing logic itself.

1. The Obsidian plugin — runs inside Obsidian, listens on localhost:14790,

and performs the actual drawing through Excalidraw's ExcalidrawAutomate API.

You need both: the plugin is the engine, the MCP server is the door the model knocks on.

---

Features

• Create rectangles, ellipses, diamonds, text, lines and arrows.
• Bound labels — text is properly nested inside shapes (centred, moves with the shape).
• Smart arrows — bind two elements, pin to a specific side (left/right/top/bottom),

elbow routing, any arrowhead, colour, width and dash style.

• Read & search — list elements with filters (by type, id, text) and choose exactly

which fields you want back.

• Edit & structure — update any property, move, recolour, rotate, group, change

z-order, delete.

• Full Excalidraw access — a generic escape hatch (eaScript / eaCall) exposes

every ExcalidrawAutomate method (images, frames, Mermaid, export, …) without needing a dedicated tool for each.

---

Requirements

| | | |---|---| | Obsidian | desktop app (this is desktop-only) | | Excalidraw plugin | installed & enabled — required dependency | | Node.js | v18 or newer (to run the MCP server) | | An MCP-capable client | Claude Desktop, Claude Code, Qwen, Cursor, … |

---

Installation

It's three things: (A) put the plugin in your vault, (B) install the MCP server, (C) point your LLM client at it. Works the same on Windows, macOS and Linux.

0. Get the code

git clone https://github.com/MultiUpGame/mcp-obsidian-excalidraw.git
cd mcp-obsidian-excalidraw

(or download the ZIP from GitHub and unzip it).

A. Install the Obsidian plugin

Copy the folder plugin/mcp-obsidian-excalidraw/ (it contains manifest.json and the prebuilt main.js) into your vault's plugins folder:

/.obsidian/plugins/mcp-obsidian-excalidraw/

How to find `: it's the folder you opened in Obsidian. The .obsidian` folder lives inside it (it may be hidden — enable "show hidden files").

• Windows example: C:\Users\You\Documents\MyVault\.obsidian\plugins\
• macOS example: /Users/You/Documents/MyVault/.obsidian/plugins/
• Linux example: /home/you/MyVault/.obsidian/plugins/

Then in Obsidian:

1. Settings → Community plugins → turn off Restricted mode (if on).
2. Click Reload plugins (or restart Obsidian).
3. Enable “MCP Obsidian Excalidraw”.

You should see a short notice that the bridge started on port 14790.

> You don't need Node.js for the plugin — main.js ships prebuilt. Node is only for > the MCP server below.

B. Install the MCP server

From the project folder:

npm install

That's the only build step. (You can test it runs with npm start, then stop it — normally your MCP client launches it for you.)

C. Register the server in your MCP client

Use the absolute path to server.js in this folder.

Claude Code (CLI):

claude mcp add --scope user excalidraw -- node /absolute/path/to/mcp-obsidian-excalidraw/server.js

Claude Desktop / Qwen / Cursor — add to the client's mcpServers config:

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-obsidian-excalidraw/server.js"]
    }
  }
}

Config file locations for Claude Desktop:

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

Restart (or reconnect) the client so it loads the new server.

Done

Open Obsidian, open an Excalidraw drawing, and ask your assistant to draw something.

---

Usage

1. Open Obsidian with an Excalidraw board open and focused, plugin enabled.
2. In your LLM client, ask in plain language:

• "Build a diagram: Frontend → Backend → Database, connected with arrows."
• "Add a red dashed arrow from the Login box to the right side of the Auth box."
• "List all rectangles and their colours."

The model picks the right tool and parameters on its own.

> Tip: if nothing happens, the model may not have targeted the board yet — it can > call setView active. The board must be open in Obsidian for drawing to land.

---

Tools

| Tool | Purpose | |------|---------| | addRect, addEllipse, addDiamond | shapes with optional bound label | | addText, addLine | free text / line | | addArrow | arrow by coordinates, or bound between two elements | | connectObjects | bound arrow between elements — side pinning, elbow, arrowheads, style | | getElements | list elements; filter by type / ids / textContains, pick fields | | getElement, searchElements | one element by id / find by text | | updateElement | change any property (position, size, colour, dash, rotation, text, …) | | deleteElement, clearBoard | remove element(s) | | setView | target the active / first Excalidraw board | | buildDiagram | build a multi-block diagram with connections in one call | | eaMethods | list every available ExcalidrawAutomate method (discovery) | | eaCall | call any EA method directly (images, frames, groups, z-order, export, …) | | eaScript | run arbitrary EA code — the escape hatch for anything not covered above |

The last three give the model access to the full Excalidraw Automate API (~140 methods) without a bespoke tool for each.

---

Security

⚠️ The plugin opens an unauthenticated HTTP server on localhost:14790 with Access-Control-Allow-Origin: *. Anything running on your machine (or local network) can send it commands, including clearBoard, and eaScript runs arbitrary code in the Obsidian context. Treat this as a local development tool. Do not expose port 14790 to untrusted networks. A future hardening step is to bind to 127.0.0.1 and require a shared token.

---

Build from source

The plugin's main.js is committed prebuilt so you can install without a toolchain. To rebuild it from plugin/mcp-obsidian-excalidraw/main.ts:

npm install
npm run build      # rollup → plugin/mcp-obsidian-excalidraw/main.js

---

Project layout

mcp-obsidian-excalidraw/
├── server.js                         # MCP server (run by your LLM client)
├── package.json / rollup.config.mjs  # deps + plugin build config
├── plugin/mcp-obsidian-excalidraw/
│   ├── main.ts                        # plugin source
│   ├── main.js                        # prebuilt plugin (copy this into your vault)
│   └── manifest.json
└── docs/                             # agent-facing usage guide & examples

---

Roadmap

• Fix addMermaid (text → diagram) wiring.
• Expose SVG / PDF export and importSVG as first-class tools.
• Optional auth (localhost bind + token) and BRAT / community-store distribution.

---

License

[MIT](LICENSE) © MultiUpGame

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MultiUpGame
• Source: MultiUpGame/mcp-obsidian-excalidraw
• License: MIT

Install and usage instructions live in the source repository linked above.