repository·main·Indexed 26 days ago
https://github.com/excalidraw/excalidraw-mcpA Model Context Protocol (MCP) server that enables AI clients to generate and display interactive, hand-drawn Excalidraw diagrams. It supports remote deployment via Vercel, local installation via stdio, and provides state persistence through CheckpointStore implementations including File, Memory, and Redis. The server includes utilities for managing editor state, computing diffs of user edits, and streaming diagrams within chat interfaces.
Once installed, you can use the server by asking your MCP-compatible client to generate diagrams. The server will stream hand-drawn Excalidraw diagrams with smooth viewport camera control and interactive fullscreen editing.
Example prompts:
For MCP clients that support custom connectors (like Claude, ChatGPT, VS Code, or Goose), you can use the recommended remote endpoint. This is the easiest way to get started without local installation.
Remote Endpoint:
https://mcp.excalidraw.com
You can install the Excalidraw MCP server locally using one of two methods:
excalidraw-mcp-app.mcpb file from the Releases page.pnpm:git clone https://github.com/excalidraw/excalidraw-mcp.git
cd excalidraw-mcp-app
pnpm install && pnpm run build~/Library/Application Support/Claude/claude_desktop_config.json:{
"mcpServers": {
"excalidraw": {
"command": "node",
"args": ["/path/to/excalidraw-mcp-app/dist/index.js", "--stdio"]
}
}
}{
"mcpServers": {
"excalidraw": {
"command": "node",
"args": ["/path/to/excalidraw-mcp-app/dist/index.js", "--stdio"]
}
}
}You can host your own instance of the Excalidraw MCP server on Vercel by following these steps:
Your deployed server will be accessible at: https://your-project.vercel.app/mcp
To use the RedisCheckpointStore (or the store returned by createVercelStore when Redis is detected), you must provide connection details via the following environment variables:
Upstash Redis / Vercel KV Variables:
KV_REST_API_URL or UPSTASH_REDIS_REST_URLKV_REST_API_TOKEN or UPSTASH_REDIS_REST_TOKENThe edit-context.ts module provides utilities for managing the lifecycle of an Excalidraw editor instance within an MCP App. It handles local storage persistence, state snapshots (checkpoints), and computing diffs of user edits to update the Model Context Protocol (MCP) model.
setStorageKey(key: string). This is typically a viewUUID or a tool-call-derived ID.checkpointId via a tool result, register it using setCheckpointId(id: string) to enable state saving.captureInitialElements(elements: readonly any[]) to establish a baseline for future diffing.onEditorChange(app: App, elements: readonly any[]) as the Excalidraw onChange handler. This function is debounced (2000ms) and performs the following:localStorage.save_checkpoint server tool if a checkpointId is set.getLatestEditedElements() to retrieve the most recent user edits.Use startStreamableHTTPServer to run the MCP server using the Streamable HTTP transport in stateless mode. This allows the server to be hosted as a web service.
PORT environment variable (defaults to 3001)./mcp.McpServer instance.Use startStdioServer to run the MCP server using the standard input/output transport. This is typically used for local integrations where the client communicates with the server process directly via stdin/stdout.
Requires a factory function that returns an McpServer instance.
The CheckpointStore interface provides a way to persist Excalidraw diagram elements (checkpoints). You can use one of the following implementations depending on your environment:
FileCheckpointStore: Persists checkpoints as JSON files in the system's temporary directory (excalidraw-mcp-checkpoints).MemoryCheckpointStore: Stores checkpoints in memory. Note that data is lost when the process restarts and it is limited to 100 entries.RedisCheckpointStore: Uses Upstash Redis to store checkpoints with a TTL of 30 days. Requires specific environment variables.createVercelStore(): A factory function that returns a RedisCheckpointStore if Redis environment variables are present, otherwise returns a MemoryCheckpointStore.All CheckpointStore implementations enforce a maximum serialized size for checkpoint data to prevent excessive resource usage.
5 * 1024 * 1024 bytes).If the JSON-serialized data exceeds this limit, the save method will throw: Checkpoint data exceeds 5242880 byte limit.
When calling save or load on any CheckpointStore implementation, the id must follow these constraints:
-), or underscores (_).If the ID violates these rules, an error will be thrown: Invalid checkpoint id: must be alphanumeric, hyphens, or underscores or Invalid checkpoint id: exceeds 64 character limit.
You can run the compiled server directly using npx or node.
npx @mcp-demos/excalidraw-serverTo run in stdio mode (instead of the default HTTP mode), pass the --stdio flag:
node dist/index.js --stdio