excalidraw-mcp
Allows AI agents to create, read, and modify Excalidraw files, generating 25+ types of hand-drawn diagrams with automatic layout, including flowcharts, architecture, sequence, mind maps, and more.
Allows importing Mermaid syntax (flowchart, sequence, class, state) to automatically generate Excalidraw diagrams.
excalidraw-mcp
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 |
Related MCP server: Excalidraw Architect MCP
Install
Claude Code (recommended)
claude mcp add excalidraw -- uvx maaker-excalidraw-mcpClaude 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-mcpTools
Tool | Description |
| Flowcharts with Sugiyama layout — branches, merges, cycles, groups |
| Layered architecture diagrams with connections |
| UML sequence diagrams with lifelines and messages |
| UML class diagrams with attributes, methods, relationships |
| UML state machines with initial/final states |
| Entity-Relationship diagrams with cardinality |
| Tree-style mind maps with auto-colored branches |
| Timeline/Gantt charts with overlapping event handling |
| Pie charts with labeled slices and percentages |
| Kanban boards with columns and cards |
| Network topology with typed nodes (server, DB, etc.) |
| 2x2 priority/positioning matrices |
| User journey maps with emotion indicators |
| UI wireframe mockups with device frames |
| Organizational charts (top-down hierarchy) |
| SWOT analysis 2x2 color-coded matrices |
| Grid tables with auto-sized columns and alternating row colors |
| Vertical bar charts with auto-scaled bars and labels |
| Line charts with multi-series support |
| Radar/spider charts with multi-series overlay |
| Decision trees with diamond decisions and rectangular outcomes |
| Import Mermaid syntax (flowchart, sequence, class, state) |
| List all available diagram types |
| Add/remove nodes and connections in existing diagrams |
| Analyze existing |
| 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 |
|
Token usage | Needs | 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
.excalidrawfile 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 fileColors: 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 filemodify_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 fileread_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 fileTechnical 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 pytestLicense
MIT
Available Tools
28 toolscreate_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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
Create, edit and organize hand-drawn diagrams (flowcharts, ER, architecture) from any AI agent.
Make editable flowcharts, process charts, funnels, timelines and data models from plain language.
Create, edit, share and export hand-drawn LetDraw diagrams, from code or a prompt.
Flowcharts that people and agents edit together on one live canvas, exported as Mermaid.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-
- FlicenseNot gradedqualityAmaintenanceEnables 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.-