| name | excalidraw-mcp-server |
| description | Build and deploy MCP servers that stream interactive Excalidraw diagrams with smooth viewport control |
| triggers | ["create an excalidraw diagram in my MCP server","add excalidraw visualization to this tool","stream a hand-drawn diagram using MCP","integrate excalidraw with model context protocol","build an interactive diagram server","render excalidraw in my AI app","create MCP app with diagrams","add visual whiteboard to my MCP tool"] |
Excalidraw MCP Server Skill
Skill by ara.so — MCP Skills collection.
This skill teaches AI agents how to build MCP servers that return interactive Excalidraw diagrams using the MCP Apps extension. Excalidraw MCP enables streaming hand-drawn style diagrams directly into AI chat interfaces like Claude Desktop, ChatGPT, VS Code, and Goose.
What It Does
The Excalidraw MCP server provides:
- Interactive diagram rendering: Returns HTML apps that render Excalidraw canvases
- Streaming updates: Supports progressive diagram building with viewport control
- Fullscreen editing: Users can click to edit diagrams in a modal
- Remote & local deployment: Run as Vercel serverless function or local Node.js process
Installation
Remote Server (Recommended)
Use the hosted version at https://mcp.excalidraw.com:
{
"mcpServers": {
"excalidraw": {
"url": "https://mcp.excalidraw.com"
}
}
}
Local Installation
From source:
git clone https://github.com/excalidraw/excalidraw-mcp.git
cd excalidraw-mcp-app
pnpm install && pnpm run build
Configure in Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"excalidraw": {
"command": "node",
"args": ["/path/to/excalidraw-mcp-app/dist/index.js", "--stdio"]
}
}
}
From release:
- Download
excalidraw-mcp-app.mcpb from releases
- Double-click to install in Claude Desktop
Core Concepts
MCP Apps Extension
MCP Apps is an official extension that lets servers return interactive HTML instead of just text. The response format:
{
content: [
{
type: "resource",
resource: {
uri: "excalidraw://diagram",
mimeType: "text/html",
text: "<html>...</html>"
}
}
]
}
Excalidraw Scene Format
Excalidraw diagrams are JSON with elements and appState:
interface ExcalidrawScene {
type: "excalidraw";
version: 2;
source: string;
elements: ExcalidrawElement[];
appState: {
viewBackgroundColor: string;
currentItemFontFamily?: number;
};
files?: Record<string, BinaryFileData>;
}
Building an Excalidraw MCP Server
Basic Server Structure
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
const server = new Server(
{
name: "excalidraw-server",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: "draw_diagram",
description: "Create an interactive Excalidraw diagram",
inputSchema: {
type: "object",
properties: {
elements: {
type: "array",
description: "Excalidraw elements (rectangles, arrows, text, etc.)",
},
description: {
type: "string",
description: "What the diagram shows",
},
},
required: ["elements"],
},
},
],
}));
server.(, (request) => {
(request.. === ) {
{ elements, description } = request.. ;
html = (elements, description);
{
: [
{
: ,
: {
: ,
: ,
: html,
},
},
],
};
}
();
});
transport = ();
server.(transport);
Generating the HTML Response
function generateExcalidrawHTML(
elements: any[],
description?: string
): string {
const scene = {
type: "excalidraw",
version: 2,
source: "mcp-server",
elements: elements,
appState: {
viewBackgroundColor: "#ffffff",
currentItemFontFamily: 1,
},
files: {},
};
const sceneJSON = JSON.stringify(scene);
return `<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>${description || "Excalidraw Diagram"}</title>
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://unpkg.com/@excalidraw/excalidraw/dist/excalidraw.production.min.js"></script>
<style>
body { margin: 0; padding: 0; overflow: hidden; }
#app { width: 100vw; height: 100vh; }
</style>
</head>
<body>
<div id="app"></div>
<script>
const { Excalidraw } = ExcalidrawLib;
const scene = ${sceneJSON};
const App = () => {
return React.createElement(Excalidraw, {
initialData: scene,
viewModeEnabled: true,
zenModeEnabled: false,
gridModeEnabled: false,
});
};
ReactDOM.render(
React.createElement(App),
document.getElementById('app')
);
</script>
</body>
</html>`;
}
Creating Excalidraw Elements
Rectangle:
{
id: "rect-1",
type: "rectangle",
x: 100,
y: 100,
width: 200,
height: 150,
strokeColor: "#1e1e1e",
backgroundColor: "#ffc9c9",
fillStyle: "hachure",
strokeWidth: 2,
roughness: 1,
opacity: 100,
angle: 0,
roundness: { type: 3 },
seed: 12345,
version: 1,
versionNonce: 1,
isDeleted: false,
groupIds: [],
boundElements: null,
}
Text:
{
id: "text-1",
type: "text",
x: 150,
y: 150,
width: 100,
height: 25,
text: "Hello World",
fontSize: 20,
fontFamily: 1,
textAlign: "center",
verticalAlign: "middle",
strokeColor: "#1e1e1e",
backgroundColor: "transparent",
fillStyle: "hachure",
strokeWidth: 2,
roughness: 1,
opacity: 100,
angle: 0,
seed: 12346,
version: 1,
versionNonce: 1,
isDeleted: false,
groupIds: [],
containerId: null,
originalText: "Hello World",
}
Arrow:
{
id: "arrow-1",
type: "arrow",
x: 300,
y: 175,
width: 150,
height: 0,
points: [[0, 0], [150, 0]],
strokeColor: "#1e1e1e",
backgroundColor: "transparent",
fillStyle: "hachure",
strokeWidth: 2,
roughness: 1,
opacity: 100,
angle: 0,
startBinding: { elementId: "rect-1", focus: 0, gap: 1 },
endBinding: { elementId: "rect-2", focus: 0, gap: 1 },
startArrowhead: null,
endArrowhead: "arrow",
seed: 12347,
version: 1,
versionNonce: 1,
isDeleted: false,
groupIds: [],
}
Ellipse:
{
id: "ellipse-1",
type: "ellipse",
x: 500,
y: 100,
width: 120,
height: 120,
strokeColor: "#2f9e44",
backgroundColor: "#d3f9d8",
fillStyle: "solid",
strokeWidth: 2,
roughness: 1,
opacity: 100,
angle: 0,
seed: 12348,
version: 1,
versionNonce: 1,
isDeleted: false,
groupIds: [],
boundElements: null,
}
Advanced Patterns
Architecture Diagram Generator
function createArchitectureDiagram(
components: { name: string; type: "user" | "server" | "database" }[]
): any[] {
const elements: any[] = [];
let xOffset = 100;
components.forEach((comp, i) => {
const id = `comp-${i}`;
const y = comp.type === "user" ? 100 : comp.type === "server" ? 300 : 500;
elements.push({
id,
type: "rectangle",
x: xOffset,
y,
width: 150,
height: 80,
strokeColor: "#1e1e1e",
backgroundColor: comp.type === "database" ? "#ffd43b" : "#a5d8ff",
fillStyle: "hachure",
strokeWidth: 2,
roughness: 1,
opacity: 100,
: ,
: { : },
: .() * ,
: ,
: ,
: ,
: [],
: ,
});
elements.({
: ,
: ,
: xOffset + ,
: y + ,
: ,
: ,
: comp.,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: .() * ,
: ,
: ,
: ,
: [],
: id,
: comp.,
});
(i < components. - ) {
elements.({
: ,
: ,
: xOffset + ,
: y + ,
: ,
: ,
: [[, ], [, ]],
: ,
: ,
: ,
: ,
: ,
: ,
: ,
: { : id, : , : },
: ,
: ,
: ,
: .() * ,
: ,
: ,
: ,
: [],
});
}
xOffset += ;
});
elements;
}
Streaming Diagrams with Updates
For progressive rendering, send multiple tool responses:
async function streamDiagram(
initialElements: any[],
updates: any[][]
): Promise<void> {
await sendToolResponse({
content: [{
type: "resource",
resource: {
uri: "excalidraw://stream-1",
mimeType: "text/html",
text: generateExcalidrawHTML(initialElements),
},
}],
});
for (const update of updates) {
await new Promise(resolve => setTimeout(resolve, 500));
const allElements = [...initialElements, ...update];
await sendToolResponse({
content: [{
type: "resource",
resource: {
uri: "excalidraw://stream-1",
mimeType: "text/html",
text: generateExcalidrawHTML(allElements),
},
}],
});
}
}
Viewport Control
function generateExcalidrawHTMLWithViewport(
elements: any[],
viewport: { x: number; y: number; zoom: number }
): string {
const scene = {
type: "excalidraw",
version: 2,
source: "mcp-server",
elements,
appState: {
viewBackgroundColor: "#ffffff",
scrollX: viewport.x,
scrollY: viewport.y,
zoom: { value: viewport.zoom },
},
files: {},
};
}
Deployment
Vercel Serverless Function
Create api/mcp.ts:
import type { VercelRequest, VercelResponse } from "@vercel/node";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
const server = new Server(
{
name: "excalidraw-server",
version: "1.0.0",
},
{
capabilities: { tools: {} },
}
);
export default async function handler(
req: VercelRequest,
res: VercelResponse
) {
const transport = new SSEServerTransport("/message", res);
await server.connect(transport);
await transport.handleRequest(req);
}
Deploy:
vercel --prod
Your server will be at https://your-project.vercel.app/api/mcp.
Docker Container
FROM node:20-alpine
WORKDIR /app
COPY package.json pnpm-lock.yaml ./
RUN npm install -g pnpm && pnpm install --frozen-lockfile
COPY . .
RUN pnpm run build
CMD ["node", "dist/index.js", "--stdio"]
docker build -t excalidraw-mcp .
docker run -i excalidraw-mcp
Troubleshooting
Elements Not Rendering
Problem: Diagram appears blank.
Solution: Ensure all required element properties are present:
{
id: string,
type: string,
x: number,
y: number,
width: number,
height: number,
seed: number,
version: number,
versionNonce: number,
isDeleted: boolean,
groupIds: string[],
}
Arrow Bindings Not Working
Problem: Arrows don't connect to shapes.
Solution: Ensure startBinding and endBinding reference valid element IDs:
{
type: "arrow",
startBinding: {
elementId: "rect-1",
focus: 0,
gap: 1,
},
endBinding: {
elementId: "rect-2",
focus: 0,
gap: 1,
},
}
Text Inside Shapes Not Centered
Problem: Text doesn't appear inside rectangles.
Solution: Set containerId to bind text to container:
{
type: "text",
containerId: "rect-1",
textAlign: "center",
verticalAlign: "middle",
}
Streaming Updates Not Appearing
Problem: Updated diagrams don't replace previous ones.
Solution: Use the same uri for all updates:
const diagramURI = `excalidraw://diagram-${sessionId}`;
resource: {
uri: diagramURI,
mimeType: "text/html",
text: generateExcalidrawHTML(updatedElements),
}
CORS Errors in Vercel Deployment
Problem: Client can't connect to Vercel MCP endpoint.
Solution: Add CORS headers in vercel.json:
{
"headers": [
{
"source": "/api/mcp",
"headers": [
{ "key": "Access-Control-Allow-Origin", "value": "*" },
{ "key": "Access-Control-Allow-Methods", "value": "GET,POST,OPTIONS" },
{ "key": "Access-Control-Allow-Headers", "value": "Content-Type" }
]
}
]
}
Best Practices
- Generate unique IDs: Use
crypto.randomUUID() or timestamps
- Set reasonable viewport: Calculate bounds from element positions
- Use consistent colors: Define a palette for visual coherence
- Add descriptions: Include metadata for accessibility
- Validate elements: Check required properties before rendering
- Handle errors gracefully: Return text fallbacks if diagram fails
- Test locally first: Use
--stdio mode before deploying remotely
Resources
