Excalidraw MCP
excalidraw mcp
Installation
npx excalidraw-mcpAsk AI about Excalidraw MCP
Powered by Claude Β· Grounded in docs
I know everything about Excalidraw MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Excalidraw MCP Server
An MCP (Model Context Protocol) server that empowers AI agents (like Claude, Cursor, Windsurf) to create, edit, and manage Excalidraw diagrams directly within your conversation.
Why Excalidraw? Its hand-drawn aesthetic and JSON-based format are perfect for rapid, programmable diagramming. This server bridges standard MCP clients with a local Excalidraw instance, enabling AI-powered visual thinking.
β¨ Features
| Feature | Description |
|---|---|
| π¨ Real-time Preview | Changes appear instantly in a local browser window via WebSocket |
| π Smart Layout | Automatically calculates text width and binds labels to containers |
| π Multi-Session | Switch between different diagrams seamlessly |
| π§ Mermaid Support | Convert Mermaid syntax to Excalidraw diagrams instantly |
| π¦ Export Options | Export to PNG, SVG, or JSON formats |
| ποΈ Templates | Built-in architecture diagram templates |
π Quick Start
You don't need to clone this repo. Just configure your MCP client:
Claude Code (cc)
claude mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcp
Codex CLI
codex mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcp
Cursor / Windsurf
Go to Settings > MCP β Add New MCP Server:
| Field | Value |
|---|---|
| Name | excalidraw |
| Type | command |
| Command | npx -y @scofieldfree/excalidraw-mcp |
Cline (VS Code Extension)
Open Cline settings and add to MCP Servers:
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}
GitHub Copilot
Use the Copilot CLI to interactively add:
/mcp add
Alternatively, create or edit ~/.copilot/mcp-config.json:
{
"mcpServers": {
"excalidraw": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}
Kiro
Follow the MCP Servers documentation. Add to .kiro/settings/mcp.json:
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}
opencode
opencode mcp add excalidraw -- npx -y @scofieldfree/excalidraw-mcp
VS Code
One-click install:
Or install via CLI:
# For VS Code
code --add-mcp '{"name":"excalidraw","command":"npx","args":["-y","@scofieldfree/excalidraw-mcp"]}'
# For VS Code Insiders
code-insiders --add-mcp '{"name":"excalidraw","command":"npx","args":["-y","@scofieldfree/excalidraw-mcp"]}'
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"excalidraw": {
"command": "npx",
"args": ["-y", "@scofieldfree/excalidraw-mcp"]
}
}
}
π οΈ Available Tools
| Tool | Description |
|---|---|
start_session | Start browser preview and open Excalidraw editor |
add_elements | Add shapes, text, arrows to the canvas |
update_element | Modify existing element properties |
delete_element | Remove elements from canvas |
get_scene | Retrieve current diagram state |
create_from_mermaid | Convert Mermaid syntax to Excalidraw |
add_template_architecture | Add a pre-built architecture diagram template |
create_diagram | Create a new diagram or clear existing |
export_diagram | Export diagram to PNG, SVG, or JSON |
list_sessions | List all active diagram sessions |
delete_diagram | Delete a diagram session |
π¬ Usage Examples
Example 1: Create a Simple Diagram
You say:
"Draw a flowchart with three boxes: Input β Process β Output"
AI uses:
start_session β add_elements (3 rectangles + 2 arrows)
Example 2: Convert Mermaid to Excalidraw
You say:
"Convert this Mermaid diagram to Excalidraw:
graph LR: A[User] --> B[API Gateway] --> C[Service] --> D[(Database)]"
AI uses:
start_session β create_from_mermaid
Example 3: Architecture Diagram
You say:
"Create an architecture diagram for a microservices system"
AI uses:
start_session β add_template_architecture (or) add_elements with custom layout
ποΈ Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β AI Agent (Claude/Cursor) β
βββββββββββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββ
β MCP Protocol (JSON-RPC over stdio)
βΌ
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Excalidraw MCP Server β
β βββββββββββββββ βββββββββββββββ βββββββββββββββββββββββ β
β β Tool Router ββββ State Store ββββ WebSocket Broadcast β β
β βββββββββββββββ βββββββββββββββ ββββββββββββ¬βββββββββββ β
ββββββββββββββββββββββββββββββββββββββββββββββββββΌβββββββββββββ
β WebSocket
βΌ
βββββββββββββββββββββββββββββββββββββ
β Browser (Excalidraw Editor) β
βββββββββββββββββββββββββββββββββββββ
π§ Development
Prerequisites
- Node.js >= 18
- pnpm >= 9
Setup
# Clone the repository
git clone https://github.com/Scofieldfree/excalidraw-mcp.git
cd excalidraw-mcp
# Install dependencies
pnpm install
# Start development server
pnpm dev
Scripts
| Command | Description |
|---|---|
pnpm dev | Start dev server (backend + frontend) |
pnpm build | Build for production |
pnpm typecheck | Run TypeScript type checking |
pnpm lint | Run ESLint |
pnpm release | Create a new release version |
π¦ Project Structure
excalidraw-mcp/
βββ packages/
β βββ mcp-server/ # Core MCP server + Excalidraw frontend
β βββ src/
β β βββ index.ts # Entry point
β β βββ state.ts # Session state management
β β βββ http-server.ts
β β βββ tools/ # MCP tool implementations
β βββ web/ # Excalidraw React frontend
βββ docs/ # Documentation
βββ package.json # Workspace configuration
π Troubleshooting
Port Already in Use
The server automatically finds an available port starting from 3100. If you need a specific port, set the PORT environment variable.
Browser Doesn't Open
Ensure you have a default browser configured. The server uses the open package to launch the browser.
WebSocket Connection Failed
Check if any firewall or antivirus is blocking WebSocket connections on localhost.
π€ Contributing
Contributions are welcome! Please read our Contributing Guide for details.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
π License
MIT Β© Scofieldfree
