Excalidraw MCP Server

Instructions

Implementation Reference

• src/operations/drawings.ts:153-188 (handler)

  Core implementation of the list_drawings tool. Lists drawings by filtering metadata files (.meta.json) from the storage directory, applies pagination based on page and perPage parameters, reads and parses metadata for each drawing, and returns the paginated list along with total count. Handles errors by returning empty list.
  export async function listDrawings(page: number = 1, perPage: number = 10): Promise<{ drawings: any[], total: number }> { await ensureStorageDir(); try { // Get all files in the storage directory const files = await fs.readdir(STORAGE_DIR); // Filter metadata files const metadataFiles = files.filter(file => file.endsWith('.meta.json')); // Calculate pagination const start = (page - 1) * perPage; const end = start + perPage; const paginatedFiles = metadataFiles.slice(start, end); // Read metadata for each drawing const drawings = await Promise.all( paginatedFiles.map(async (file) => { const metadataPath = path.join(STORAGE_DIR, file); const metadataStr = await fs.readFile(metadataPath, 'utf-8'); return JSON.parse(metadataStr); }) ); return { drawings, total: metadataFiles.length, }; } catch (error) { console.error('Failed to list drawings:', error); return { drawings: [], total: 0, }; } }
• src/operations/drawings.ts:42-45 (schema)

  Zod schema defining input parameters for list_drawings tool: optional page (default 1) and perPage (default 10, max 100). Used for validation in both registration and dispatch.
  export const ListDrawingsSchema = z.object({ page: z.number().int().min(1).optional().default(1), perPage: z.number().int().min(1).max(100).optional().default(10), });
• index.ts:83-86 (registration)

  Tool registration in the ListTools response, specifying name, description, and input schema.
  name: "list_drawings", description: "List all Excalidraw drawings", inputSchema: zodToJsonSchema(drawings.ListDrawingsSchema), },
• index.ts:145-151 (handler)

  Dispatch handler in the main CallToolRequestHandler switch statement. Parses arguments using the schema, calls the core listDrawings function, and formats result as MCP content.
  case "list_drawings": { const args = drawings.ListDrawingsSchema.parse(request.params.arguments); const result = await drawings.listDrawings(args.page, args.perPage); return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], }; }