Excalidraw MCP Agent 🎨

Local Model Context Protocol (MCP) server that generates beautifully formatted, hand-drawn Excalidraw diagrams (.excalidraw) directly from natural language text prompts or structured descriptions.

---

🌟 Features

• Prompt-to-Diagram Generator: Create complex architecture diagrams, flowcharts, and system pipelines directly from free-text prompts (generate_diagram_from_prompt).
• Structured MCP Control: Fine-grained shape control (create_excalidraw_diagram) supporting Rectangles, Diamonds, Ellipses, and Arrow labels.
• Dynamic Geometry Engine:
  • Auto-calculates box dimensions and text metrics to eliminate text clipping.
  • Native Virgil hand-drawn font rendering with 100% mathematical text centering inside containers.
  • Smart perimeter intersection math (getNodeEdgePoint) preventing arrows from crossing through shapes.
  • Directional perpendicular arrow label offsets preventing line collisions.
• Excalidraw Browser Integration: Open generated diagrams directly on excalidraw.com via open_excalidraw_diagram.

---

📦 Installation & Setup

1. Clone & Install Dependencies

git clone https://github.com/Anuraj4/Excalidraw-MCP-Agent.git
cd Excalidraw-MCP-Agent
npm install

2. Link Binary Globally

Link the package binary globally so any MCP client can run excalidraw-mcp-agent:

npm link

---

⚙️ MCP Client Configuration

Add the server entry to your MCP client configuration file (e.g. Claude Desktop, Cursor, VS Code, or Antigravity Desktop):

Option A: Using the Globally Linked Command (Recommended)

{
  "mcpServers": {
    "excalidraw": {
      "command": "excalidraw-mcp-agent",
      "env": {
        "EXCALIDRAW_WORKSPACE": "C:\\path\\to\\your\\workspace"
      }
    }
  }
}

Option B: Using Node Directly

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": [
        "C:\\path\\to\\Excalidraw-MCP-Agent\\src\\server.js"
      ],
      "env": {
        "EXCALIDRAW_WORKSPACE": "C:\\path\\to\\your\\workspace"
      }
    }
  }
}

---

🛠️ Available MCP Tools

Tool	Description
generate_diagram_from_prompt	Generates a complete Excalidraw diagram directly from a natural language prompt string.
create_excalidraw_diagram	Generates a diagram from structured nodes and arrows with custom geometry and colors.
list_excalidraw_diagrams	Lists all .excalidraw diagram files in the current workspace directory.
open_excalidraw_diagram	Launches excalidraw.com in your browser to inspect or edit a file.

---

🎨 Diagram Palette & Style Guidelines

The builder applies color palettes and shape semantics automatically according to standard architectural conventions:

Component Type	Color	Shape
Actors / Users / Clients	purple	Ellipse
Ingestion / Data Sources	blue	Rectangle
Processing / Logic	green	Rectangle
Database / Vector DB / Storage	cyan	Rectangle
Decisions / Conditionals	yellow	Diamond
Output / ERP / External Systems	orange	Rectangle
Exceptions / Errors / Warnings	red	Rectangle

---

💡 Prompt Examples

Once configured, simply interact with your AI assistant using prompts like:

• RAG Architecture:

  "Create an Excalidraw diagram for a RAG system: User uploads PDFs -> Chunking & embedding -> Vector DB -> User query -> Similarity search -> LLM answer generation."

• Invoice Extraction Pipeline:

  "Generate an Excalidraw flowchart for Invoice Data Extraction: Supplier submits invoice -> Document Ingestion -> Classification (Invoice vs Receipt) -> Check valid invoice -> Key data extraction -> Validation rules check -> ERP integration export (if valid) or Exception Queue (if error)."

---

🧪 Testing

Run unit tests and end-to-end stdio MCP integration tests:

npm test

---

📄 License

MIT