Figma MCP

Instructions

Implementation Reference

• src/tools/handlers/screenshot.js:4-71 (handler)

  Core handler function that captures a screenshot of a specified Figma frame. Handles finding the page and frame, fetches the image from Figma API, segments large images into tiles if exceeding maxDimension, and returns structured content with navigation info and base64 image data.
  export async function getScreenshot(ctx, fileKey, pageName, frameName, scale, maxDimension) { const { chunker, figmaClient } = ctx; const file = await figmaClient.getFile(fileKey, 2); const page = figmaClient.findPageByName(file, pageName); if (!page) throw new Error(`Page "${pageName}" not found`); const frame = figmaClient.findFrameByName(page, frameName); if (!frame) throw new Error(`Frame "${frameName}" not found`); const width = (frame.absoluteBoundingBox?.width || 0) * scale; const height = (frame.absoluteBoundingBox?.height || 0) * scale; const imageData = await figmaClient.getImage(fileKey, frame.id, "png", scale); const imageUrl = imageData.images[frame.id]; if (!imageUrl) throw new Error("Failed to generate image"); const response = await axios.get(imageUrl, { responseType: "arraybuffer" }); if (width > maxDimension || height > maxDimension) { const tiles = await segmentImage(response.data, { width, height, maxDimension, }); const navInfo = chunker.wrapResponse( { frame: frame.name, width: Math.round(width), height: Math.round(height), tiles: tiles.length }, { step: `Screenshot segmented into ${tiles.length} tiles`, progress: "Complete", nextStep: "Use get_frame_info for structure details", } ); return { content: [ { type: "text", text: JSON.stringify(navInfo, null, 2) }, ...tiles.map((tile) => ({ type: "image", data: tile.data, mimeType: "image/png", })), ], }; } const navInfo = chunker.wrapResponse( { frame: frame.name, width: Math.round(width), height: Math.round(height) }, { step: "Screenshot captured", progress: "Complete", nextStep: "Use get_frame_info for structure, or extract_assets for icons/images", } ); return { content: [ { type: "text", text: JSON.stringify(navInfo, null, 2) }, { type: "image", data: Buffer.from(response.data).toString("base64"), mimeType: "image/png", }, ], }; }
• src/tools/schemas.js:93-121 (schema)

  Tool schema definition including name, description, and input schema for validating parameters like file_key, page_name, frame_name, scale, and max_dimension.
  { name: "get_screenshot", description: `Capture screenshot of a frame. WARNING: Do NOT use screenshots as the first step! Always call get_frame_info first to understand the structure. Screenshots are for visual reference AFTER you understand the tree. HOW IT WORKS: - For large frames, automatically segments into tiles - Returns base64 image(s) - Scale 1-4 controls resolution TYPICAL WORKFLOW: 1. list_frames → find frame 2. get_frame_info → structure details 3. get_screenshot → visual reference`, inputSchema: { type: "object", properties: { file_key: { type: "string", description: "Figma file key" }, page_name: { type: "string", description: "Page name (partial match)" }, frame_name: { type: "string", description: "Frame name (partial match)" }, scale: { type: "number", description: "Scale 1-4 (default: 2)", default: 2 }, max_dimension: { type: "number", description: "Max px before segmenting (default: 4096)", default: 4096 }, }, required: ["file_key", "page_name", "frame_name"], }, },
• src/index.js:54-56 (registration)

  Registration of the get_screenshot tool in the MCP server's CallToolRequest handler switch statement, mapping the tool name to the handlers.getScreenshot function call.
  case "get_screenshot": result = await handlers.getScreenshot(this.ctx, args.file_key, args.page_name, args.frame_name, args.scale || 2, args.max_dimension || 4096); break;
• src/tools/handlers/index.js:2-2 (registration)

  Export statement that makes the getScreenshot handler available from the handlers index module, allowing import * as handlers.
  export { getScreenshot } from "./screenshot.js";
• src/tools/handlers/screenshot.js:124-168 (helper)

  Helper function used by the handler to segment large screenshots into smaller tiles for images exceeding the maxDimension, producing base64 data for each tile.
  async function segmentImage(buffer, options) { const { width, height, maxDimension = 4096, transparencyRegions = [], mode = 'tiles', } = options; let processedBuffer = buffer; if (transparencyRegions.length > 0) { processedBuffer = await applyTransparency(buffer, transparencyRegions, height); } const image = sharp(processedBuffer); const metadata = await image.metadata(); const cols = Math.ceil(metadata.width / maxDimension); const rows = Math.ceil(metadata.height / maxDimension); const tileWidth = Math.ceil(metadata.width / cols); const tileHeight = Math.ceil(metadata.height / rows); const tiles = []; for (let row = 0; row < rows; row++) { for (let col = 0; col < cols; col++) { const left = col * tileWidth; const top = row * tileHeight; const extractWidth = Math.min(tileWidth, metadata.width - left); const extractHeight = Math.min(tileHeight, metadata.height - top); const tile = await sharp(processedBuffer) .extract({ left, top, width: extractWidth, height: extractHeight }) .png() .toBuffer(); tiles.push({ row, col, data: tile.toString("base64"), }); } } return tiles; }