excalidraw-mcp-server

Instructions

Implementation Reference

• src/mcp/tools/read-me.ts:9-18 (handler)

  The main handler function for the read_me tool that returns the cheatsheet content as formatted text
  export async function handleReadMe(): Promise<{ content: Array<{ type: 'text'; text: string }>; }> { return { content: [{ type: 'text' as const, text: getCheatsheetText(), }], }; }
• src/mcp/apps/cheatsheet.ts:105-156 (helper)

  Helper function that generates the formatted cheatsheet text with element types, color palettes, sizing guidelines, and tips
  export function getCheatsheetText(): string { const ref = ELEMENT_REFERENCE; const lines: string[] = []; lines.push('# Excalidraw MCP Quick Reference\n'); lines.push('## Element Types\n'); for (const [name, info] of Object.entries(ref.types)) { lines.push(`### ${name}`); lines.push(info.description); lines.push(`Required: ${info.requiredFields.join(', ')}`); if (info.optionalFields) { lines.push(`Optional: ${info.optionalFields.join(', ')}`); } if ('defaults' in info && info.defaults) { lines.push(`Defaults: ${JSON.stringify(info.defaults)}`); } if ('example' in info && info.example) { lines.push(`Example: ${JSON.stringify(info.example)}`); } lines.push(''); } lines.push('## Color Palettes\n'); for (const [name, palette] of Object.entries(ref.colorPalettes)) { lines.push(`### ${name} - ${palette.description}`); for (const [colorName, hex] of Object.entries(palette.colors)) { lines.push(` ${colorName}: ${hex}`); } lines.push(''); } lines.push('## Sizing Guidelines\n'); for (const [key, val] of Object.entries(ref.sizing)) { if (typeof val === 'string') { lines.push(`- ${key}: ${val}`); } else { lines.push(`- ${key}:`); for (const [k, v] of Object.entries(val)) { lines.push(` ${k}: ${v}px`); } } } lines.push(''); lines.push('## Tips\n'); for (const tip of ref.tips) { lines.push(`- ${tip}`); } return lines.join('\n'); }
• src/mcp/apps/cheatsheet.ts:7-103 (schema)

  Data structure defining all element types, color palettes, sizing rules, and best practices that the read_me tool returns
  export const ELEMENT_REFERENCE = { types: { rectangle: { description: 'Rectangular shape. Use for boxes, containers, cards.', requiredFields: ['x', 'y'], optionalFields: ['width', 'height', 'backgroundColor', 'strokeColor', 'text'], defaults: { width: 200, height: 100 }, }, ellipse: { description: 'Oval/circle shape. Use for nodes, badges, indicators.', requiredFields: ['x', 'y'], optionalFields: ['width', 'height', 'backgroundColor', 'strokeColor', 'text'], defaults: { width: 150, height: 150 }, }, diamond: { description: 'Diamond/rhombus shape. Use for decision points in flowcharts.', requiredFields: ['x', 'y'], optionalFields: ['width', 'height', 'backgroundColor', 'strokeColor', 'text'], defaults: { width: 150, height: 150 }, }, arrow: { description: 'Directional arrow connecting points. Use for flows and relationships.', requiredFields: ['x', 'y', 'points'], optionalFields: ['strokeColor', 'strokeWidth'], example: { x: 0, y: 0, points: [{ x: 0, y: 0 }, { x: 200, y: 0 }] }, }, line: { description: 'Straight or polyline segment. Use for dividers, connections without direction.', requiredFields: ['x', 'y', 'points'], optionalFields: ['strokeColor', 'strokeWidth'], }, text: { description: 'Standalone text label. Use for titles, annotations, labels.', requiredFields: ['x', 'y', 'text'], optionalFields: ['fontSize', 'fontFamily'], defaults: { fontSize: 20 }, }, freedraw: { description: 'Freehand drawing path. Use for sketchy annotations.', requiredFields: ['x', 'y', 'points'], optionalFields: ['strokeColor', 'strokeWidth'], }, }, colorPalettes: { excalidraw: { description: 'Default Excalidraw hand-drawn palette', colors: { blue: '#1971c2', red: '#c92a2a', green: '#2f9e44', orange: '#e67700', yellow: '#f59f00', purple: '#6741d9', pink: '#c2255c', gray: '#868e96', black: '#1b1b1f', white: '#ffffff', }, }, pastel: { description: 'Soft pastel backgrounds for containers and cards', colors: { lightBlue: '#d0ebff', lightRed: '#ffe3e3', lightGreen: '#d3f9d8', lightOrange: '#fff4e6', lightYellow: '#fff9db', lightPurple: '#e5dbff', lightPink: '#ffdeeb', lightGray: '#f1f3f5', }, }, }, sizing: { spacing: 'Keep 40-60px between elements for readable layouts', textInBox: 'Add 20px padding around text inside rectangles', arrowGap: 'Start arrows 10px from source edge, end 10px before target', minWidth: 'Minimum readable element width is 80px', fontSize: { title: 28, heading: 22, body: 16, caption: 12, }, }, tips: [ 'Use batch_create_elements to place multiple elements at once - faster than individual creates', 'Group related elements with group_elements after creating them', 'Use align_elements and distribute_elements to clean up layouts', 'For flowcharts: diamond = decision, rectangle = process, ellipse = start/end', 'Set roughness: 0 for clean lines, 1 for hand-drawn look, 2 for sketchy', 'Lock elements with lock_elements to prevent accidental changes to finished sections', ], };
• src/mcp/apps/register.ts:57-72 (registration)

  Registration of the read_me tool with the MCP server, including its description and handler wiring
  // Register read_me as a regular tool (no UI needed) server.tool( 'read_me', 'Get the Excalidraw element reference: types, colors, sizing, and tips. Call this before creating diagrams.', {}, async () => { try { return await handleReadMe(); } catch (err) { return { content: [{ type: 'text' as const, text: `Error: ${(err as Error).message}` }], isError: true, }; } } );
• src/mcp/index.ts:58-72 (registration)

  Calls registerMcpApps to register the read_me tool along with other MCP Apps tools and resources
  // Register MCP Apps tools (create_view, read_me) and widget resource const __dirname = path.dirname(fileURLToPath(import.meta.url)); registerMcpApps(server, { getWidgetHtml: async () => { const widgetPath = path.resolve(__dirname, '../widget/index.html'); try { return await fs.promises.readFile(widgetPath, 'utf-8'); } catch { return '<html><body><p>Widget not built. Run npm run build:widget</p></body></html>'; } }, persistToStore: async (elements) => { await client.batchCreate(elements); }, });