{"_id":"excalidraw-mcp-server","_rev":"4-0d40398934c52d1b973b3d24c1f09cde","name":"excalidraw-mcp-server","dist-tags":{"latest":"2.0.0"},"versions":{"1.0.0":{"name":"excalidraw-mcp-server","version":"1.0.0","keywords":["excalidraw","mcp","model-context-protocol","diagramming","security","websocket","real-time"],"author":{"name":"Debu Sinha"},"license":"MIT","_id":"excalidraw-mcp-server@1.0.0","maintainers":[{"name":"debu-sinha","email":"debusinha2009@gmail.com"}],"homepage":"https://github.com/debu-sinha/excalidraw-mcp-server#readme","bugs":{"url":"https://github.com/debu-sinha/excalidraw-mcp-server/issues"},"bin":{"excalidraw-mcp-server":"dist/mcp/index.js"},"dist":{"shasum":"32cc27e0d67e4acbb50820f8c9993a4dc54110d5","tarball":"https://registry.npmjs.org/excalidraw-mcp-server/-/excalidraw-mcp-server-1.0.0.tgz","fileCount":282,"integrity":"sha512-cE0YZgpBB+/wj+rr2VwIxoFJui0wBX9jq3rwrPo01SENUBY6lgNPPaBHzli/r/4PXL+pJil3XJZ7grde/qgsXg==","signatures":[{"sig":"MEUCIGKKbRXOlcXcjbAd5admNm7stQo8tQ3QrWHfhHM7UeYqAiEAndGi9wTbgKWGjp9tKawR8St+bC405PgvT8GP2XIYt2M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9048974},"main":"dist/mcp/index.js","type":"module","types":"./dist/mcp/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"478c41d0b4aaa4e6720c126a6a7df93b2717afa2","scripts":{"dev":"concurrently \"tsc -p tsconfig.json --watch\" \"vite\"","lint":"eslint src test","test":"vitest run","build":"npm run build:server && npm run build:frontend","start":"node dist/mcp/index.js","canvas":"node dist/canvas/index.js","format":"prettier --write src test","lint:fix":"eslint --fix src test","test:watch":"vitest","type-check":"tsc --noEmit","build:server":"tsc -p tsconfig.json","generate-key":"node scripts/generate-api-key.cjs","test:coverage":"vitest run --coverage","build:frontend":"vite build","prepublishOnly":"npm run lint && npm run type-check && npm run test && npm run build"},"_npmUser":{"name":"debu-sinha","email":"debusinha2009@gmail.com"},"repository":{"url":"git+https://github.com/debu-sinha/excalidraw-mcp-server.git","type":"git"},"_npmVersion":"10.9.4","description":"Security-hardened MCP server for Excalidraw with API key auth, rate limiting, and real-time canvas sync","directories":{},"_nodeVersion":"22.21.1","dependencies":{"ws":"^8.18.0","zod":"^3.23.8","cors":"^2.8.5","pino":"^9.5.0","react":"^18.3.1","helmet":"^8.0.0","express":"^4.21.3","mermaid":"^11.12.1","react-dom":"^18.3.1","pino-pretty":"^13.0.0","express-rate-limit":"^7.4.0","@excalidraw/excalidraw":"^0.18.0","@modelcontextprotocol/sdk":"^1.26.0","@excalidraw/mermaid-to-excalidraw":"^1.1.3"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.3.5","eslint":"^9.16.0","vitest":"^2.1.0","prettier":"^3.4.0","@types/ws":"^8.5.10","typescript":"^5.8.3","@types/cors":"^2.8.17","@types/node":"^20.19.7","@types/react":"^18.3.3","concurrently":"^9.2.0","@types/express":"^4.17.21","@types/react-dom":"^18.3.0","@vitest/coverage-v8":"^2.1.0","@vitejs/plugin-react":"^4.6.0","@typescript-eslint/parser":"^8.18.0","@typescript-eslint/eslint-plugin":"^8.18.0"},"_npmOperationalInternal":{"tmp":"tmp/excalidraw-mcp-server_1.0.0_1770507816322_0.13710262361750192","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"excalidraw-mcp-server","version":"1.0.1","keywords":["excalidraw","mcp","model-context-protocol","diagramming","security","websocket","real-time"],"author":{"name":"Debu Sinha"},"license":"MIT","_id":"excalidraw-mcp-server@1.0.1","maintainers":[{"name":"debu-sinha","email":"debusinha2009@gmail.com"}],"homepage":"https://github.com/debu-sinha/excalidraw-mcp-server#readme","bugs":{"url":"https://github.com/debu-sinha/excalidraw-mcp-server/issues"},"bin":{"excalidraw-mcp-server":"dist/mcp/index.js"},"dist":{"shasum":"cde32ecf8624b781dfdb32215fa6a28821db4164","tarball":"https://registry.npmjs.org/excalidraw-mcp-server/-/excalidraw-mcp-server-1.0.1.tgz","fileCount":282,"integrity":"sha512-fo6HRhzHc/d49tzC52zhJXz/n31QbNmTQGhu5G/8000IdD98N+uA/IByyKAjxOb2risDDi0fq5lHq4K7j+qXhg==","signatures":[{"sig":"MEYCIQCpBaOMIBPbNL/IQtmrB7lqlviX6l+hikevZCFjh0t3VwIhAPMOmpHzpXgGEsToYbjeoylxkmEMckuLC8DC4hiEVwTZ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9049023},"main":"dist/mcp/index.js","type":"module","types":"./dist/mcp/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"478c41d0b4aaa4e6720c126a6a7df93b2717afa2","mcpName":"io.github.debu-sinha/excalidraw","scripts":{"dev":"concurrently \"tsc -p tsconfig.json --watch\" \"vite\"","lint":"eslint src test","test":"vitest run","build":"npm run build:server && npm run build:frontend","start":"node dist/mcp/index.js","canvas":"node dist/canvas/index.js","format":"prettier --write src test","lint:fix":"eslint --fix src test","test:watch":"vitest","type-check":"tsc --noEmit","build:server":"tsc -p tsconfig.json","generate-key":"node scripts/generate-api-key.cjs","test:coverage":"vitest run --coverage","build:frontend":"vite build","prepublishOnly":"npm run lint && npm run type-check && npm run test && npm run build"},"_npmUser":{"name":"debu-sinha","email":"debusinha2009@gmail.com"},"repository":{"url":"git+https://github.com/debu-sinha/excalidraw-mcp-server.git","type":"git"},"_npmVersion":"10.9.4","description":"Security-hardened MCP server for Excalidraw with API key auth, rate limiting, and real-time canvas sync","directories":{},"_nodeVersion":"22.21.1","dependencies":{"ws":"^8.18.0","zod":"^3.23.8","cors":"^2.8.5","pino":"^9.5.0","react":"^18.3.1","helmet":"^8.0.0","express":"^4.21.3","mermaid":"^11.12.1","react-dom":"^18.3.1","pino-pretty":"^13.0.0","express-rate-limit":"^7.4.0","@excalidraw/excalidraw":"^0.18.0","@modelcontextprotocol/sdk":"^1.26.0","@excalidraw/mermaid-to-excalidraw":"^1.1.3"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.3.5","eslint":"^9.16.0","vitest":"^2.1.0","prettier":"^3.4.0","@types/ws":"^8.5.10","typescript":"^5.8.3","@types/cors":"^2.8.17","@types/node":"^20.19.7","@types/react":"^18.3.3","concurrently":"^9.2.0","@types/express":"^4.17.21","@types/react-dom":"^18.3.0","@vitest/coverage-v8":"^2.1.0","@vitejs/plugin-react":"^4.6.0","@typescript-eslint/parser":"^8.18.0","@typescript-eslint/eslint-plugin":"^8.18.0"},"_npmOperationalInternal":{"tmp":"tmp/excalidraw-mcp-server_1.0.1_1770508276491_0.815702299859212","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"excalidraw-mcp-server","version":"1.0.2","keywords":["excalidraw","mcp","model-context-protocol","diagramming","security","websocket","real-time"],"author":{"name":"Debu Sinha"},"license":"MIT","_id":"excalidraw-mcp-server@1.0.2","maintainers":[{"name":"debu-sinha","email":"debusinha2009@gmail.com"}],"homepage":"https://github.com/debu-sinha/excalidraw-mcp-server#readme","bugs":{"url":"https://github.com/debu-sinha/excalidraw-mcp-server/issues"},"bin":{"excalidraw-mcp-server":"dist/mcp/index.js"},"dist":{"shasum":"3e7e6db3695b089b3a2b374cf3e4184f467bacab","tarball":"https://registry.npmjs.org/excalidraw-mcp-server/-/excalidraw-mcp-server-1.0.2.tgz","fileCount":282,"integrity":"sha512-AZvD3+i/Nzm+lsNw14iFkh9R6GjZmeNRYOnY/pILBbqEJdlaxRqLrAsEak4px+Gh/Bv07qZNuC1wNm43pYHXrg==","signatures":[{"sig":"MEUCIQDvJh5Qk18gNSQzesbWXYe/vba4VcpUGQaguqTF3vFLtwIgOnM6ImxSv8+TgEmA4rdERVZPg46WL2K6RLUQplVr2bw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":9049561},"main":"dist/mcp/index.js","type":"module","types":"./dist/mcp/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"1dc6bf278b92afc182e941a5f6a45f62f2b980e4","mcpName":"io.github.debu-sinha/excalidraw","scripts":{"dev":"concurrently \"tsc -p tsconfig.json --watch\" \"vite\"","lint":"eslint src test","test":"vitest run","build":"npm run build:server && npm run build:frontend","start":"node dist/mcp/index.js","canvas":"node dist/canvas/index.js","format":"prettier --write src test","lint:fix":"eslint --fix src test","test:watch":"vitest","type-check":"tsc --noEmit","build:server":"tsc -p tsconfig.json","generate-key":"node scripts/generate-api-key.cjs","test:coverage":"vitest run --coverage","build:frontend":"vite build","prepublishOnly":"npm run lint && npm run type-check && npm run test && npm run build"},"_npmUser":{"name":"debu-sinha","email":"debusinha2009@gmail.com"},"repository":{"url":"git+https://github.com/debu-sinha/excalidraw-mcp-server.git","type":"git"},"_npmVersion":"10.9.4","description":"Security-hardened MCP server for Excalidraw with API key auth, rate limiting, and real-time canvas sync","directories":{},"_nodeVersion":"22.21.1","dependencies":{"ws":"^8.18.0","zod":"^3.23.8","cors":"^2.8.5","pino":"^9.5.0","react":"^18.3.1","helmet":"^8.0.0","express":"^4.21.3","mermaid":"^11.12.1","react-dom":"^18.3.1","pino-pretty":"^13.0.0","express-rate-limit":"^7.4.0","@excalidraw/excalidraw":"^0.18.0","@modelcontextprotocol/sdk":"^1.26.0","@excalidraw/mermaid-to-excalidraw":"^1.1.3"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.3.5","eslint":"^9.16.0","vitest":"^2.1.0","prettier":"^3.4.0","@types/ws":"^8.5.10","typescript":"^5.8.3","@types/cors":"^2.8.17","@types/node":"^20.19.7","@types/react":"^18.3.3","concurrently":"^9.2.0","@types/express":"^4.17.21","@types/react-dom":"^18.3.0","@vitest/coverage-v8":"^2.1.0","@vitejs/plugin-react":"^4.6.0","@typescript-eslint/parser":"^8.18.0","@typescript-eslint/eslint-plugin":"^8.18.0"},"_npmOperationalInternal":{"tmp":"tmp/excalidraw-mcp-server_1.0.2_1770509064135_0.7663875209920692","host":"s3://npm-registry-packages-npm-production"}},"2.0.0":{"name":"excalidraw-mcp-server","mcpName":"io.github.debu-sinha/excalidraw","version":"2.0.0","description":"Security-hardened MCP server for Excalidraw with API key auth, rate limiting, and real-time canvas sync","main":"dist/mcp/index.js","type":"module","bin":{"excalidraw-mcp-server":"dist/mcp/index.js"},"scripts":{"start":"node dist/mcp/index.js","canvas":"node dist/canvas/index.js","build":"npm run build:server && npm run build:widget && npm run build:frontend","build:server":"tsc -p tsconfig.json","build:widget":"vite build --config vite.widget.config.ts","build:frontend":"vite build","dev":"concurrently \"tsc -p tsconfig.json --watch\" \"vite\"","lint":"eslint src test","lint:fix":"eslint --fix src test","format":"prettier --write src test","type-check":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublishOnly":"npm run lint && npm run type-check && npm run test && npm run build","generate-key":"node scripts/generate-api-key.cjs"},"dependencies":{"@excalidraw/excalidraw":"^0.18.0","@excalidraw/mermaid-to-excalidraw":"^1.1.3","@modelcontextprotocol/ext-apps":"^1.0.1","@modelcontextprotocol/sdk":"^1.26.0","cors":"^2.8.5","express":"^4.21.3","express-rate-limit":"^7.4.0","helmet":"^8.0.0","mermaid":"^11.12.1","pino":"^9.5.0","pino-pretty":"^13.0.0","react":"^18.3.1","react-dom":"^18.3.1","vite-plugin-singlefile":"^2.3.0","ws":"^8.18.0","zod":"^3.23.8"},"devDependencies":{"@types/cors":"^2.8.17","@types/express":"^4.17.21","@types/node":"^20.19.7","@types/react":"^18.3.3","@types/react-dom":"^18.3.0","@types/ws":"^8.5.10","@typescript-eslint/eslint-plugin":"^8.18.0","@typescript-eslint/parser":"^8.18.0","@vitejs/plugin-react":"^4.6.0","@vitest/coverage-v8":"^2.1.0","concurrently":"^9.2.0","eslint":"^9.16.0","prettier":"^3.4.0","typescript":"^5.8.3","vite":"^6.3.5","vitest":"^2.1.0"},"author":{"name":"Debu Sinha"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/debu-sinha/excalidraw-mcp-server.git"},"keywords":["excalidraw","mcp","model-context-protocol","diagramming","security","websocket","real-time"],"engines":{"node":">=18.0.0"},"_id":"excalidraw-mcp-server@2.0.0","gitHead":"455da65654d4a91a09a1d1fabea6acd100a1dbda","types":"./dist/mcp/index.d.ts","bugs":{"url":"https://github.com/debu-sinha/excalidraw-mcp-server/issues"},"homepage":"https://github.com/debu-sinha/excalidraw-mcp-server#readme","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-ibx/RzqltM5oxLMt4Rd3vbCXsfVJn1gPzubZgc7a+XVdFzLa8Yyvv2sGImc3qQlVfcJA05mxDRkneC9w9wxz5Q==","shasum":"15afa7b636830ebb97d0f474d2001253016d9bb1","tarball":"https://registry.npmjs.org/excalidraw-mcp-server/-/excalidraw-mcp-server-2.0.0.tgz","fileCount":304,"unpackedSize":9471890,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDxzEbUTy9/d8uASa0og+1aIsI7hm5tg8UXWwN+3zBqHQIhALZUk5EgnyBRk2jAhYzbMM8SCzUxL/VGn7z/KNcK2ILN"}]},"_npmUser":{"name":"debu-sinha","email":"debusinha2009@gmail.com"},"directories":{},"maintainers":[{"name":"debu-sinha","email":"debusinha2009@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/excalidraw-mcp-server_2.0.0_1770518760593_0.9013535986256773"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-07T23:43:36.321Z","modified":"2026-02-08T02:46:00.989Z","1.0.0":"2026-02-07T23:43:36.621Z","1.0.1":"2026-02-07T23:51:16.778Z","1.0.2":"2026-02-08T00:04:24.434Z","2.0.0":"2026-02-08T02:46:00.863Z"},"bugs":{"url":"https://github.com/debu-sinha/excalidraw-mcp-server/issues"},"author":{"name":"Debu Sinha"},"license":"MIT","homepage":"https://github.com/debu-sinha/excalidraw-mcp-server#readme","keywords":["excalidraw","mcp","model-context-protocol","diagramming","security","websocket","real-time"],"repository":{"type":"git","url":"git+https://github.com/debu-sinha/excalidraw-mcp-server.git"},"description":"Security-hardened MCP server for Excalidraw with API key auth, rate limiting, and real-time canvas sync","maintainers":[{"name":"debu-sinha","email":"debusinha2009@gmail.com"}],"readme":"# excalidraw-mcp-server\r\n\r\nThe only Excalidraw MCP server with security hardening, inline diagram rendering, and real-time canvas sync.\r\n\r\n[![CI](https://github.com/debu-sinha/excalidraw-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/debu-sinha/excalidraw-mcp-server/actions/workflows/ci.yml)\r\n[![npm](https://img.shields.io/npm/v/excalidraw-mcp-server)](https://www.npmjs.com/package/excalidraw-mcp-server)\r\n[![npm downloads](https://img.shields.io/npm/dt/excalidraw-mcp-server)](https://www.npmjs.com/package/excalidraw-mcp-server)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\r\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)\r\n\r\n## What it does\r\n\r\nAsk your AI to draw a diagram, and it appears right inside the chat. The MCP server gives Claude Desktop, ChatGPT, VS Code, and Cursor a full set of drawing tools backed by the Excalidraw format -- with API authentication, rate limiting, and input validation on every operation.\r\n\r\nv2.0 adds **MCP Apps support**: diagrams stream inline as interactive SVG widgets with draw-on animations, and you can export any diagram to excalidraw.com with one click.\r\n\r\n## Two modes, zero config\r\n\r\n**Standalone mode** (default) -- just install and go. The server runs with an in-process element store. No canvas server, no API keys, no setup. Your MCP client calls the tools, and diagrams render inline.\r\n\r\n**Connected mode** -- start the optional canvas server for real-time browser sync. Multiple clients can collaborate on the same canvas through authenticated WebSocket connections. File persistence keeps state across restarts.\r\n\r\nThe server auto-detects which mode to use: if a canvas server is reachable, it connects to it. Otherwise it falls back to standalone.\r\n\r\n## Architecture\r\n\r\n<p align=\"center\">\r\n  <img src=\"docs/architecture-v2.svg\" alt=\"Architecture: MCP clients connect via stdio to the server, which operates in standalone mode with an in-process store and inline widget, or in connected mode with a canvas server, WebSocket browser frontend, and file persistence\" width=\"800\" />\r\n</p>\r\n\r\n*Diagram created with excalidraw-mcp-server -- [edit in Excalidraw](docs/architecture-v2.excalidraw.json)*\r\n\r\n## Features\r\n\r\n**MCP Apps (v2.0)**\r\n- Inline diagram rendering in Claude Desktop, ChatGPT, and VS Code\r\n- Streaming SVG with draw-on animations as elements arrive\r\n- Export to excalidraw.com with one click\r\n- Element reference cheatsheet via `read_me` tool\r\n\r\n**16 MCP tools**\r\n- Create, update, delete, and query elements (rectangle, ellipse, diamond, arrow, text, line, freedraw)\r\n- Batch create up to 100 elements at once\r\n- Group, ungroup, align, distribute, lock, unlock\r\n- Mermaid diagram conversion\r\n- SVG and PNG export\r\n\r\n**Security**\r\n- API key authentication with constant-time comparison\r\n- Origin-restricted CORS (no wildcards)\r\n- WebSocket auth with token and origin validation\r\n- Standard and strict rate limiting tiers\r\n- Bounded Zod schemas with `.strict()` on every endpoint\r\n- Helmet.js security headers with CSP\r\n\r\n**Infrastructure**\r\n- Real-time WebSocket sync across browser clients\r\n- Optional atomic-write file persistence\r\n- Structured pino audit logging\r\n\r\n## Install\r\n\r\n```bash\r\nnpm install -g excalidraw-mcp-server\r\n```\r\n\r\nOr run directly:\r\n\r\n```bash\r\nnpx excalidraw-mcp-server\r\n```\r\n\r\n## Quick start\r\n\r\n### Standalone (recommended for most users)\r\n\r\nJust point your MCP client at the server. No canvas server needed.\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"excalidraw\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"excalidraw-mcp-server\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nThen ask your AI: *\"Draw an architecture diagram showing a load balancer, three app servers, and a database\"*\r\n\r\n### Connected mode (real-time browser sync)\r\n\r\n```bash\r\n# Generate an API key\r\nnode scripts/generate-api-key.cjs\r\n\r\n# Start the canvas server\r\nEXCALIDRAW_API_KEY=<your-key> npm run canvas\r\n\r\n# Open http://localhost:3000 to see the live canvas\r\n```\r\n\r\nPoint your MCP client at the server with the same API key:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"excalidraw\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"excalidraw-mcp-server\"],\r\n      \"env\": {\r\n        \"EXCALIDRAW_API_KEY\": \"<your-key>\",\r\n        \"CANVAS_SERVER_URL\": \"http://127.0.0.1:3000\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n## MCP tools\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `create_view` | Render elements as an inline SVG widget with streaming animations (MCP Apps) |\r\n| `read_me` | Get the element reference cheatsheet (types, colors, sizing tips) |\r\n| `create_element` | Create a single element (rectangle, ellipse, diamond, arrow, text, line, freedraw) |\r\n| `update_element` | Update an existing element by ID |\r\n| `delete_element` | Delete an element by ID |\r\n| `query_elements` | Search elements by type, locked status, or group ID |\r\n| `get_resource` | Get scene state, all elements, theme, or library |\r\n| `batch_create_elements` | Create up to 100 elements in one call |\r\n| `group_elements` | Group multiple elements together |\r\n| `ungroup_elements` | Remove elements from a group |\r\n| `align_elements` | Align elements (left, center, right, top, middle, bottom) |\r\n| `distribute_elements` | Distribute elements evenly (horizontal or vertical) |\r\n| `lock_elements` | Lock elements to prevent modification |\r\n| `unlock_elements` | Unlock elements |\r\n| `create_from_mermaid` | Convert a Mermaid diagram to Excalidraw elements |\r\n| `export_scene` | Export the canvas as SVG or PNG |\r\n\r\n## Security comparison\r\n\r\n| Feature | Typical MCP servers | excalidraw-mcp-server |\r\n|---------|--------------------|-----------------------|\r\n| Authentication | None | API key (constant-time compare) |\r\n| CORS | `*` wildcard | Origin allowlist |\r\n| WebSocket auth | None | Token + origin validation |\r\n| Rate limiting | None | Standard + strict tiers |\r\n| Input validation | Minimal | Bounded Zod with `.strict()` |\r\n| Security headers | None | Helmet.js + CSP |\r\n| Request size limit | None | 512KB body, 1MB WebSocket |\r\n| Audit logging | None | Structured pino logs |\r\n\r\n## Configuration\r\n\r\nAll settings via environment variables. Copy `.env.example` to `.env` and adjust as needed.\r\n\r\n| Variable | Default | Description |\r\n|----------|---------|-------------|\r\n| `STANDALONE_MODE` | `true` | Use in-process store (no canvas server needed) |\r\n| `CANVAS_HOST` | `127.0.0.1` | Canvas server bind address |\r\n| `CANVAS_PORT` | `3000` | Canvas server port |\r\n| `EXCALIDRAW_API_KEY` | Auto-generated | API key for auth (min 32 chars) |\r\n| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000,http://127.0.0.1:3000` | Comma-separated origin allowlist |\r\n| `RATE_LIMIT_WINDOW_MS` | `60000` | Rate limit window in milliseconds |\r\n| `RATE_LIMIT_MAX_REQUESTS` | `100` | Max requests per window (standard tier) |\r\n| `PERSISTENCE_ENABLED` | `false` | Enable file-based persistence |\r\n| `PERSISTENCE_DIR` | `./data` | Directory for persistent storage |\r\n| `CANVAS_SERVER_URL` | `http://127.0.0.1:3000` | URL the MCP server uses to reach the canvas |\r\n| `LOG_LEVEL` | `info` | Log level: debug, info, warn, error |\r\n| `AUDIT_LOG_ENABLED` | `true` | Enable audit logging |\r\n| `MAX_ELEMENTS` | `10000` | Maximum elements on canvas |\r\n| `MAX_BATCH_SIZE` | `100` | Maximum elements per batch create |\r\n\r\n## MCP client configuration\r\n\r\n### Claude Desktop\r\n\r\nAdd to `claude_desktop_config.json`:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"excalidraw\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"excalidraw-mcp-server\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Cursor\r\n\r\nAdd to `.cursor/mcp.json` in your project root:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"excalidraw\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"excalidraw-mcp-server\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### VS Code\r\n\r\nAdd to your MCP settings:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"excalidraw\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"excalidraw-mcp-server\"]\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nFor connected mode, add `\"env\": { \"EXCALIDRAW_API_KEY\": \"<key>\", \"CANVAS_SERVER_URL\": \"http://127.0.0.1:3000\" }` to the config above. Replace `<key>` with the key from `node scripts/generate-api-key.cjs`.\r\n\r\n## Development\r\n\r\n```bash\r\n# Install dependencies\r\nnpm ci\r\n\r\n# Run in development mode (watch + Vite dev server)\r\nnpm run dev\r\n\r\n# Run tests\r\nnpm test\r\n\r\n# Run tests with coverage\r\nnpm run test:coverage\r\n\r\n# Lint\r\nnpm run lint\r\n\r\n# Type check\r\nnpm run type-check\r\n\r\n# Build (server + widget + frontend)\r\nnpm run build\r\n```\r\n\r\n## Project structure\r\n\r\n```\r\nsrc/\r\n  mcp/              MCP server (stdio transport)\r\n    tools/          16 tool implementations\r\n    apps/           MCP Apps wiring, standalone store, cheatsheet\r\n    schemas/        Zod schemas and input limits\r\n    canvas-client.ts  HTTP client for canvas server\r\n    index.ts        MCP server entry point\r\n  canvas/           Canvas server (Express + WebSocket)\r\n    middleware/      Auth, CORS, rate limiting, audit, security headers\r\n    routes/         REST API routes + SVG export\r\n    ws/             WebSocket handler and protocol\r\n    store/          Element storage (memory + file)\r\n    index.ts        Canvas server entry point\r\n  shared/           Shared config, types, logging\r\nwidget/             MCP Apps inline widget (Vite + singlefile build)\r\nfrontend/           Excalidraw React frontend (browser)\r\ntest/               Unit and integration tests (290 tests)\r\n```\r\n\r\n## Migrating from v1.x\r\n\r\nZero-config upgrade. All 14 original tools work identically -- `create_view` and `read_me` are additive. The canvas server is now optional (standalone mode activates automatically).\r\n\r\n```bash\r\nnpm install -g excalidraw-mcp-server@2\r\n```\r\n\r\nExisting MCP client configs (stdio transport, tool names) continue to work without changes.\r\n\r\n## License\r\n\r\n[MIT](LICENSE)\r\n","readmeFilename":"README.md"}