Figma MCP

Instructions

Implementation Reference

• src/tools/handlers/navigation.js:3-59 (handler)

  The core handler function that lists pages in a Figma file, handles chunking for large files, and manages session state.

  export async function listPages(ctx, fileKey, continueFlag = false) {
    const { session, chunker, figmaClient } = ctx;
    const operationId = `list_pages:${fileKey}`;
  
    if (continueFlag && session.hasPendingChunks(operationId)) {
      const chunk = session.getNextChunk(operationId);
      const response = chunker.wrapResponse(
        { pages: chunk.items },
        {
          step: `Showing pages ${(chunk.chunkIndex - 1) * 20 + 1}-${Math.min(chunk.chunkIndex * 20, chunk.totalItems)}`,
          progress: `${chunk.chunkIndex}/${chunk.totalChunks}`,
          nextStep: chunk.chunkIndex < chunk.totalChunks ? "Call with continue=true for more" : "Use list_frames to explore a page",
          operationId,
        }
      );
      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
    }
  
    session.setCurrentFile(fileKey);
    const file = await figmaClient.getFile(fileKey, 1);
  
    const pages = file.document.children.map((page) => {
      session.markPageExplored(page.id);
      return {
        name: page.name,
        id: page.id,
        frameCount: page.children?.filter((c) => c.type === "FRAME" || c.type === "COMPONENT").length || 0,
      };
    });
  
    const chunked = chunker.chunkArray(pages, operationId, 20);
  
    if (chunked) {
      const response = chunker.wrapResponse(
        { file: file.name, lastModified: file.lastModified, pages: chunked.items },
        {
          step: `Showing pages 1-${chunked.items.length} of ${chunked.totalItems}`,
          progress: `1/${chunked.totalChunks}`,
          nextStep: "Call with continue=true for more pages, or use list_frames to explore",
          alert: `File has ${pages.length} pages - showing first ${chunked.items.length}`,
          operationId,
        }
      );
      return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
    }
  
    const response = chunker.wrapResponse(
      { file: file.name, lastModified: file.lastModified, pages },
      {
        step: "Listed all pages",
        progress: `${pages.length} pages`,
        nextStep: "Use list_frames(page_name) to explore frames in a page",
      }
    );
  
    return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
  }

• src/tools/schemas.js:2-29 (schema)

  JSON Schema defining the input parameters (file_key required, continue optional) and description for the list_pages tool.

    {
      name: "list_pages",
      description: `List all pages in a Figma file.
  
  HOW IT WORKS:
  - Returns compact JSON with page names, IDs, and frame counts
  - Large files (>50 pages) are automatically chunked
  - Use 'continue: true' to get next batch
  
  TYPICAL WORKFLOW:
  1. list_pages → see all pages
  2. list_frames(page_name) → see frames in a page
  3. get_frame_info(frame_name) → detail one frame`,
      inputSchema: {
        type: "object",
        properties: {
          file_key: {
            type: "string",
            description: "Figma file key from URL (e.g., 'h75vgHNcwxfHkRBbI53RRu')",
          },
          continue: {
            type: "boolean",
            description: "Continue from last response if more pages available",
          },
        },
        required: ["file_key"],
      },
    },

• src/index.js:45-46 (registration)

  Dispatch case in the main server handler that routes list_pages calls to the listPages function.

  case "list_pages":
    result = await handlers.listPages(this.ctx, args.file_key, args.continue);

• src/tools/handlers/index.js:1-1 (registration)

  Re-export of the listPages handler for use in the main index.js.

  export { listPages, listFrames, getFrameInfo } from "./navigation.js";

• src/index.js:31-32 (registration)

  Registration of tool list endpoint which includes the list_pages schema via toolSchemas import.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: toolSchemas,