Skip to main content
Glama

excalidraw-mcp

PyPI Downloads License: MIT

Generate 25+ types of beautiful hand-drawn diagrams with AI — flowcharts, sequence, architecture, mind maps, ER, class, state, timeline, pie/bar/line/radar charts, kanban, wireframes, decision trees, and more — with Sugiyama hierarchical layout, CJK support, and zero learning curve.

By Maaker.AI

Showcase

Every image below was generated by a single tool call — no coordinates, no manual layout. The .excalidraw sources live in docs/showcase/; drag any of them onto excalidraw.com to keep editing.

Flowchart (branches + cycle + CJK)

Layered architecture

Flowchart

Architecture

Mind map

Related MCP server: Excalidraw Architect MCP

Install

claude mcp add excalidraw -- uvx maaker-excalidraw-mcp

Claude Desktop

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

opencode / Cursor / any MCP client

{
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["uvx", "maaker-excalidraw-mcp"],
      "enabled": true
    }
  }
}

(opencode shown; Cursor and other clients use the same uvx maaker-excalidraw-mcp command in their MCP config format.)

pip

pip install maaker-excalidraw-mcp

Tools

Tool

Description

create_flowchart

Flowcharts with Sugiyama layout — branches, merges, cycles, groups

create_architecture_diagram

Layered architecture diagrams with connections

create_sequence_diagram

UML sequence diagrams with lifelines and messages

create_class_diagram

UML class diagrams with attributes, methods, relationships

create_state_diagram

UML state machines with initial/final states

create_er_diagram

Entity-Relationship diagrams with cardinality

create_mindmap

Tree-style mind maps with auto-colored branches

create_timeline

Timeline/Gantt charts with overlapping event handling

create_pie_chart

Pie charts with labeled slices and percentages

create_kanban_board

Kanban boards with columns and cards

create_network_diagram

Network topology with typed nodes (server, DB, etc.)

create_quadrant_chart

2x2 priority/positioning matrices

create_user_journey

User journey maps with emotion indicators

create_wireframe

UI wireframe mockups with device frames

create_org_chart

Organizational charts (top-down hierarchy)

create_swot_analysis

SWOT analysis 2x2 color-coded matrices

create_table

Grid tables with auto-sized columns and alternating row colors

create_bar_chart

Vertical bar charts with auto-scaled bars and labels

create_line_chart

Line charts with multi-series support

create_radar_chart

Radar/spider charts with multi-series overlay

create_decision_tree

Decision trees with diamond decisions and rectangular outcomes

import_mermaid

Import Mermaid syntax (flowchart, sequence, class, state)

list_diagram_types

List all available diagram types

modify_diagram

Add/remove nodes and connections in existing diagrams

read_diagram

Analyze existing .excalidraw files

export_diagram

Export diagrams to SVG format

Quick Examples

Flowchart

Just tell your AI assistant:

"Create a flowchart: User Request → Load Balancer → API Server → Database"

The AI will call create_flowchart with structured data, and you'll get a .excalidraw file with:

  • Sugiyama hierarchical layout — proper handling of branches, merges, cycles, and disconnected subgraphs

  • Auto-calculated box sizes based on text content

  • Perfectly centered text (including Chinese/CJK characters)

  • Smart arrow routing with proper edge binding

  • Hand-drawn style that looks great in docs and presentations

  • 4 directions: LR (left-to-right), RL, TB (top-to-bottom), BT

Architecture Diagram

"Create an architecture diagram with Frontend (React, Next.js), Backend (API Server, Auth Service), and Database (PostgreSQL, Redis) layers"

Generates a layered diagram with components organized by tier, automatic sizing, and connections between layers.

Read & Modify

"Read the diagram at ./my-system.excalidraw and add a 'Cache' node connected to the API Server"

Works with existing .excalidraw files — read their structure, add/remove nodes, add connections.

Why excalidraw-mcp?

vs Official Excalidraw MCP (excalidraw/excalidraw-mcp)

Feature

Official MCP

excalidraw-mcp

Approach

Raw JSON — AI manually places every element

Structured input — say what you want, get a diagram

Layout

AI calculates coordinates

Sugiyama hierarchical auto-layout

Branches/Merges

AI must figure out positioning

Automatic — handled by layout engine

CJK text

No width estimation

Accurate CJK/mixed-script width calculation

Text centering

AI must calculate x/y offsets

Automatic centering in containers

Arrow binding

AI must manage bindings

Automatic fixedPoint + orbit binding

Local files

Cannot read/write local files

Full read, modify, save support

Distribution

Remote URL / .mcpb

uvx / pip (standard Python)

Token usage

Needs read_me call to learn format

Format knowledge built-in

vs Mermaid-based tools

  • Free layout: Not constrained by Mermaid syntax limitations

  • Hand-drawn style: Native Excalidraw look, not rendered code blocks

  • Editable output: Drag the .excalidraw file to excalidraw.com to continue editing

Tool Reference

create_flowchart

Input:
  nodes: [{label: "Step 1", color?: "blue", shape?: "rectangle"}]
  edges: [{from: "Step 1", to: "Step 2", label?: "next"}]
  direction?: "LR" | "RL" | "TB" | "BT"  (default: "LR")
  title?: "My Flowchart"
  output_path?: "/path/to/output.excalidraw"

Output: Path to generated .excalidraw file

Colors: blue, green, purple, yellow, red, gray, orange, pink

Shapes: rectangle (default), diamond (decisions), ellipse (start/end)

create_architecture_diagram

Input:
  layers: [{
    name: "Frontend",
    color?: "blue",
    components: [{label: "React"}, {label: "Next.js"}]
  }]
  connections?: [{from: "React", to: "API Server"}]
  output_path?: "/path/to/output.excalidraw"

Output: Path to generated .excalidraw file

modify_diagram

Input:
  file_path: "/path/to/existing.excalidraw"
  add_nodes?: [{label: "New Node", color?: "green", x?: 100, y?: 100}]
  remove_labels?: ["Old Node"]
  add_connections?: [{from: "A", to: "B"}]
  output_path?: "/path/to/output.excalidraw"

Output: Path to modified file

read_diagram

Input:
  file_path: "/path/to/diagram.excalidraw"

Output: Structured description (shapes, connections, colors)

export_diagram

Input:
  file_path: "/path/to/diagram.excalidraw"
  format: "svg"

Output: Path to exported SVG file

Technical Details

Sugiyama Hierarchical Layout

Uses the grandalf library for proper directed graph layout:

  • Layer assignment: Nodes placed in layers based on graph topology

  • Crossing minimization: Multi-pass optimization to reduce edge crossings

  • Coordinate assignment: Balanced positioning within layers

  • Cycle handling: Feedback edge detection for cyclic graphs

  • Disconnected subgraphs: Automatic side-by-side placement

CJK Width Estimation

Accurate text width calculation for mixed Chinese/English text:

Character Type

Width (at fontSize=20)

CJK characters

~22px per character

ASCII letters/digits

~11px per character

Spaces

~5px

Arrow Binding

Uses Excalidraw's modern fixedPoint + orbit binding (not the deprecated focus/gap format):

{
  "startBinding": {
    "elementId": "box1",
    "fixedPoint": [1.0, 0.5001],
    "mode": "orbit"
  }
}

Arrows automatically connect at the correct edge based on relative positions.

Development

git clone https://github.com/maaker-ai/excalidraw-mcp.git
cd excalidraw-mcp
uv sync --dev
uv run pytest

License

MIT

Available Tools

28 tools
create_architecture_diagramB

Create a layered architecture diagram.

Args: layers: List of layers, each with 'name' and 'components' list. Example: [{"name": "Frontend", "color": "blue", "components": [{"label": "React App"}, {"label": "Next.js"}]}] connections: List of connections between components. Example: [{"from": "React App", "to": "API Server"}] output_path: Optional output file path

Returns: Path to the generated .excalidraw file

Inputs: layers (required), theme, connections, output_path. Returns: result

create_bar_chartA

Create a vertical bar chart.

Generates a bar chart with auto-scaled bars, value labels, and axis labels.

Args: bars: List of bars with label and value title: Optional chart title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: bars (required), theme, title, output_path. Returns: result

create_class_diagramA

Create a UML class diagram.

Generates a class diagram with class boxes showing attributes and methods, connected by relationship arrows (inheritance, composition, etc.).

Args: classes: List of class definitions with name, attributes, and methods relationships: List of relationships between classes title: Optional diagram title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: classes (required), theme, title, output_path, +1 more. Returns: result

create_decision_treeA

Create a decision tree diagram.

Generates a tree with diamond-shaped decision nodes and rectangular outcome nodes, connected by labeled edges.

Args: nodes: List of nodes with id, label, and type edges: List of edges with from, to, and optional label title: Optional diagram title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: edges (required), nodes (required), theme, title, +1 more. Returns: result

create_diagramA

Create any type of diagram with a single unified tool.

This is a convenience tool that routes to the specific diagram tool based on the diagram_type parameter. Use list_diagram_types to see all available types.

Args: diagram_type: Type of diagram (flowchart, sequence, mindmap, er, class, state, timeline, pie, kanban, network, quadrant, journey, wireframe, org, swot, architecture) data: Diagram-specific data (varies by type) title: Optional diagram title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Path to generated file or error message

Inputs: data (required), diagram_type (required), theme, title, +1 more. Returns: result

create_er_diagramA

Create an Entity-Relationship (ER) diagram.

Generates a database-style ER diagram with entity boxes showing attributes and relationship arrows with cardinality labels.

Args: entities: List of entities with name and attributes relationships: List of relationships between entities title: Optional diagram title output_path: Optional output file path

Returns: Absolute path to the generated .excalidraw file

Inputs: entities (required), theme, title, output_path, +1 more. Returns: result

create_flowchartA

Create a flowchart diagram with Sugiyama hierarchical auto-layout.

Generates a hand-drawn style Excalidraw flowchart from nodes and edges. Handles branches, merges, cycles, and disconnected subgraphs. Supports Chinese/CJK text with accurate width estimation.

Args: nodes: List of nodes with label and optional color edges: List of edges connecting nodes (by label or 0-based index) direction: Layout direction - "LR" (left to right), "RL", "TB" (top to bottom), "BT" title: Optional diagram title output_path: Optional output file path (default: /tmp/flowchart.excalidraw) theme: Color theme - "light" (default) or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: edges (required), nodes (required), theme, title, +2 more. Returns: result

create_kanban_boardA

Create a Kanban board diagram.

Generates a column-based task board with cards in each column. Great for visualizing workflows, sprints, and task status.

Args: columns: List of columns with name and card labels title: Optional board title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: columns (required), theme, title, output_path. Returns: result

create_line_chartB

Create a line chart with one or more data series.

Generates a line chart with auto-scaled Y axis, X-axis labels, and color-coded series.

Args: series: List of data series with label and points x_labels: Labels for the X axis title: Optional chart title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: series (required), x_labels (required), theme, title, +1 more. Returns: result

create_mindmapA

Create a mind map diagram from a tree structure.

Generates a tree-style mind map with the root node in the center-left and branches spreading to the right. Each top-level branch gets a distinct color.

Args: root: Root node with label and optional children (nested tree) title: Optional diagram title output_path: Optional output file path (default: /tmp/mindmap.excalidraw)

Returns: Absolute path to the generated .excalidraw file

Inputs: root (required), theme, title, output_path. Returns: result

create_network_diagramA

Create a network topology diagram.

Generates a network diagram with typed nodes (server, database, loadbalancer, etc.) and connections. Different node types get distinct shapes and colors.

Args: nodes: List of network nodes with type links: List of connections between nodes title: Optional diagram title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: nodes (required), links, theme, title, +1 more. Returns: result

create_org_chartB

Create an organizational chart.

Generates a top-down hierarchical org chart from a tree structure. Each node can have a title/description and subordinates.

Args: root: Root node with label and optional children title: Optional chart title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: root (required), theme, title, output_path. Returns: result

create_pie_chartA

Create a pie chart diagram.

Generates a pie chart with labeled slices showing proportions. Each slice displays its label and percentage.

Args: slices: List of slices with label and value title: Optional chart title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: slices (required), theme, title, output_path. Returns: result

create_quadrant_chartA

Create a quadrant (2x2 matrix) chart.

Generates a four-quadrant chart for positioning items along two axes. Great for priority matrices, effort/impact charts, and positioning maps.

Args: items: List of items with label and x/y position (0-1 range) x_label: X axis label (e.g., "Effort") y_label: Y axis label (e.g., "Impact") quadrant_labels: Optional 4 labels [top-right, top-left, bottom-right, bottom-left] title: Optional chart title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: items (required), theme, title, x_label, +3 more. Returns: result

create_radar_chartA

Create a radar/spider chart.

Generates a radar chart with axes radiating from center. Supports single or multiple data series overlay.

Args: axes: List of axis names (minimum 3) values: Single set of values (0-1), one per axis series: Multiple series for comparison title: Optional chart title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: axes (required), theme, title, series, +2 more. Returns: result

create_sequence_diagramA

Create a UML-style sequence diagram.

Generates a hand-drawn style sequence diagram with participants, lifelines, and messages. Supports solid arrows for requests and dashed arrows for responses.

Args: participants: List of participant names (ordered left to right) messages: List of messages with from, to, label, and optional style title: Optional diagram title output_path: Optional output file path (default: /tmp/sequence.excalidraw)

Returns: Absolute path to the generated .excalidraw file

Inputs: messages (required), participants (required), theme, title, +1 more. Returns: result

create_state_diagramA

Create a UML state machine diagram.

Generates a state diagram with states (rounded rectangles), initial states (filled circles), final states (double border), and transition arrows with labels.

Args: states: List of state definitions transitions: List of transitions between states title: Optional diagram title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: states (required), transitions (required), theme, title, +1 more. Returns: result

create_swot_analysisA

Create a SWOT analysis diagram.

Generates a color-coded 2x2 SWOT matrix with bullet-pointed items in each quadrant (Strengths, Weaknesses, Opportunities, Threats).

Args: strengths: List of strength items weaknesses: List of weakness items opportunities: List of opportunity items threats: List of threat items title: Optional diagram title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: theme, title, threats, strengths, +3 more. Returns: result

create_tableA

Create a table diagram.

Generates a grid-based table with header row and data rows. Auto-sizes columns based on content. Great for comparison tables, feature matrices, and data displays.

Args: headers: Column header labels rows: List of rows, each row is a list of cell values title: Optional table title header_color: Header row color name output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: rows (required), headers (required), theme, title, +2 more. Returns: result

create_timelineA

Create a timeline / Gantt chart diagram.

Generates a horizontal bar chart showing events/tasks over time. Overlapping events are automatically placed on separate rows.

Args: events: List of events with label, start, end, and optional color title: Optional diagram title output_path: Optional output file path (default: /tmp/timeline.excalidraw) theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: events (required), theme, title, output_path. Returns: result

create_user_journeyA

Create a user journey map.

Generates a horizontal journey map showing steps with emotion indicators. Each step shows a label, emotion (color-coded), and optional description.

Args: steps: List of journey steps with label and emotion title: Optional journey title output_path: Optional output file path theme: Color theme - "light" or "dark"

Returns: Absolute path to the generated .excalidraw file

Inputs: steps (required), theme, title, output_path. Returns: result

create_wireframeA

Create a wireframe UI mockup.

Generates a simple wireframe with common UI components stacked vertically. Great for quick screen mockups and UI planning.

Component types:

  • header: Full-width header bar

  • text: Plain text block

  • button: Centered button

  • input: Text input field

  • image: Image placeholder

  • card: Content card

  • nav: Navigation bar

  • divider: Horizontal line

Args: components: List of UI components in order device: Device frame: "phone", "tablet", "desktop", "none" title: Optional wireframe title output_path: Optional output file path theme: Color theme

Returns: Absolute path to the generated .excalidraw file

Inputs: components (required), theme, title, device, +1 more. Returns: result

export_diagramA

Export an .excalidraw file to SVG format.

Args: file_path: Path to the .excalidraw file format: Export format - currently "svg" supported

Returns: Path to the exported file

Inputs: file_path (required), format. Returns: result

import_mermaidB

Import any Mermaid diagram and convert to Excalidraw.

Auto-detects diagram type (flowchart or sequence diagram) and generates the appropriate Excalidraw diagram.

Args: mermaid: Mermaid diagram text (flowchart or sequenceDiagram) output_path: Optional output file path

Returns: Absolute path to the generated .excalidraw file

Inputs: mermaid (required), theme, output_path. Returns: result

import_mermaid_flowchartA

Import a Mermaid flowchart and convert to Excalidraw.

Parses Mermaid flowchart syntax and generates a hand-drawn Excalidraw diagram with Sugiyama layout.

Args: mermaid: Mermaid flowchart text output_path: Optional output file path

Returns: Absolute path to the generated .excalidraw file

Inputs: mermaid (required), theme, output_path. Returns: result

list_diagram_typesA

List all available diagram types and tools.

Returns a formatted list of all diagram types this MCP server can generate, with tool names and descriptions.

Returns: Formatted list of available diagram types

Inputs: no named parameters. Returns: result

modify_diagramA

Modify an existing .excalidraw diagram.

Args: file_path: Path to existing .excalidraw file add_nodes: Nodes to add: [{"label": "New Node", "color": "green", "x": 100, "y": 100}] remove_labels: Labels of nodes to remove add_connections: New connections: [{"from": "Node A", "to": "Node B"}] output_path: Optional output path (default: overwrite input file)

Returns: Path to the modified file

Inputs: file_path (required), add_nodes, output_path, remove_labels, +1 more. Returns: result

read_diagramA

Read and analyze an existing .excalidraw file.

Returns a structured description of the diagram including:

  • List of shapes with labels and positions

  • List of connections between shapes

  • Color scheme used

Args: file_path: Path to the .excalidraw file

Returns: Human-readable description of the diagram structure

Inputs: file_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 28 tools

    Disambiguation3/5

    Most tools are clearly separated by diagram type (flowchart, sequence, ER, etc.), but there is meaningful overlap: import_mermaid subsumes import_mermaid_flowchart, create_diagram duplicates every create_* tool, and several tree-like diagram tools (flowchart, org chart, mindmap, decision tree) could be confused for generic hierarchy requests. Descriptions help, but the boundaries are not always crisp.

    Naming Consistency4/5

    The create_<diagram_type> convention is consistent and predictable across the majority of tools, making the set easy to scan. Minor deviations include import_mermaid vs. import_mermaid_flowchart, the generic create_diagram, and a few names like create_swot_analysis that break the diagram suffix pattern.

    Tool Count3/5

    28 tools is on the heavy side, though the breadth of diagram types partially justifies it. The count is inflated by redundancy: import_mermaid_flowchart is largely subsumed by import_mermaid, create_diagram duplicates all specialized creators, and list_diagram_types is a metadata helper rather than a core operation.

    Completeness4/5

    The server covers a wide range of diagram creation plus modify, read, export, and Mermaid import, so most user workflows have a path to completion. Minor gaps exist around full edit fidelity—modify_diagram only supports adding/removing nodes and connections, not arbitrary repositioning or restyling—and there is no support for importing other diagram formats.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to turn plain-language descriptions of systems, flows, and data into 25 kinds of fully laid-out, hand-drawn Excalidraw diagrams — architecture, sequence, ER, swimlane, Gantt, charts and more — with auto-styling for 50+ technologies and revision in natural language. Runs fully offline, exports to SVG and PNG without a browser or Node.js, and can optionally persist the architecture as a queryable knowledge graph.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables users to generate and revise 25 types of hand-drawn Excalidraw diagrams—including architecture, flowcharts, sequence, ER, Gantt, and charts—from natural-language specs without managing coordinates. It can also persist architecture as a queryable, version-controlled knowledge graph and export offline to SVG or PNG.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to generate auto-laid-out, hand-drawn-style Excalidraw diagrams across 25 diagram types from natural-language structure descriptions, with SVG/PNG export and natural-language revision. Runs fully offline without API keys and can persist the described system as a queryable architecture knowledge graph.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding tools to turn architecture and other structured descriptions into auto-laid-out, hand-drawn Excalidraw diagrams across 25 diagram types, including architecture, flowcharts, sequence, ER, swimlanes, timelines, Gantt, and charts. It also supports natural-language revision, SVG/PNG export, and optionally a queryable knowledge graph of the system.
      -