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.

Related MCP server: Excalidraw MCP Server

📦 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

🎨 Diagram Palette & Style Guidelines

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

💡 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