How to add Excalidraw Architect MCP to Windsurf

Turn architecture into a queryable knowledge graph and render auto-laid-out Excalidraw diagrams. Offline, no API keys. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 125★ · stdio · no auth

Windsurf config for Excalidraw Architect MCP

pip install excalidraw-architect-mcp

{
  "mcpServers": {
    "excalidraw-architect-mcp": {
      "command": "excalidraw-architect-mcp",
      "args": []
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Excalidraw Architect MCP config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Excalidraw Architect MCP's tools become available to Cascade.

Before you start

Python with pip (or uv/uvx to run without installing)
An MCP-compatible IDE (Cursor, Claude Code, Windsurf)
Optional: cairosvg for PNG export (pip install excalidraw-architect-mcp[png])
Optional: Excalidraw VS Code extension or excalidraw.com to view .excalidraw files

What Excalidraw Architect MCP can do in Windsurf

create_diagram

Create a new diagram from structured node/connection data.

mermaid_to_excalidraw

Convert Mermaid flowchart syntax to a .excalidraw file.

modify_diagram

Add/remove/update nodes and connections on an existing diagram.

get_diagram_info

Read current diagram state (call before modifying).

export_diagram

Export a .excalidraw file to an SVG or PNG image.

kg_init

Create a new knowledge graph file.

kg_add_service

Add or update a service (with type, domain, owner, tags, links).

kg_remove_service

Remove a service from the knowledge graph.

Security

Runs fully offline over stdio with no API keys or network calls. The server reads and writes `.excalidraw` and `.claude/architecture.md` files on the local filesystem. Optional PNG export requires the extra `cairosvg` dependency (`pip install excalidraw-architect-mcp[png]`).

Excalidraw Architect MCP + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Excalidraw Architect MCP config there under the "mcpServers" key and restart the client.

Is Excalidraw Architect MCP safe to use with Windsurf?

Does it require API keys or network access?

No. It runs fully offline over stdio in Cursor, Claude Code, and Windsurf with no API keys.

How do I export diagrams to images?

SVG export works out of the box via a pure-Python renderer (no browser needed). PNG export requires the optional cairosvg dependency: pip install excalidraw-architect-mcp[png], and supports a configurable resolution multiplier (default 2x).

What is the architecture knowledge graph?

A persistent, version-controlled model of your system stored in a single markdown file (default .claude/architecture.md). It is the source of truth, and diagrams are rendered views — full system, a domain, or a service's N-hop neighborhood. It round-trips losslessly whether edited by hand or by the AI.

View repo Full Excalidraw Architect MCP page