create_text
Add text elements to Figma designs by specifying position, content, font size, weight, color, and layer organization.
Instructions
Create a new text element in Figma
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| x | Yes | X position | |
| y | Yes | Y position | |
| text | Yes | Text content | |
| fontSize | No | Font size (default: 14) | |
| fontWeight | No | Font weight (e.g., 400 for Regular, 700 for Bold) | |
| fontColor | No | Font color in RGBA format | |
| name | No | Semantic layer name for the text node | |
| parentId | No | Optional parent node ID to append the text to |
Implementation Reference
- src/cursor_mcp_plugin/code.js:289-384 (handler)Core handler function for the 'create_text' tool. Creates a Figma TextNode, sets position, loads 'Inter' font based on weight, applies font size, sets text content using setCharacters helper, applies solid fill color, appends to specified parent or current page, and returns node details.
async function createText(params) { const { x = 0, y = 0, text = "Text", fontSize = 14, fontWeight = 400, fontColor = { r: 0, g: 0, b: 0, a: 1 }, // Default to black name = "Text", parentId, } = params || {}; // Map common font weights to Figma font styles const getFontStyle = (weight) => { switch (weight) { case 100: return "Thin"; case 200: return "Extra Light"; case 300: return "Light"; case 400: return "Regular"; case 500: return "Medium"; case 600: return "Semi Bold"; case 700: return "Bold"; case 800: return "Extra Bold"; case 900: return "Black"; default: return "Regular"; } }; const textNode = figma.createText(); textNode.x = x; textNode.y = y; textNode.name = name; try { await figma.loadFontAsync({ family: "Inter", style: getFontStyle(fontWeight), }); textNode.fontName = { family: "Inter", style: getFontStyle(fontWeight) }; textNode.fontSize = parseInt(fontSize); } catch (error) { console.error("Error setting font size", error); } setCharacters(textNode, text); // Set text color const paintStyle = { type: "SOLID", color: { r: parseFloat(fontColor.r) || 0, g: parseFloat(fontColor.g) || 0, b: parseFloat(fontColor.b) || 0, }, opacity: parseFloat(fontColor.a) || 1, }; textNode.fills = [paintStyle]; // If parentId is provided, append to that node, otherwise append to current page if (parentId) { const parentNode = await figma.getNodeByIdAsync(parentId); if (!parentNode) { throw new Error(`Parent node not found with ID: ${parentId}`); } if (!("appendChild" in parentNode)) { throw new Error(`Parent node does not support children: ${parentId}`); } parentNode.appendChild(textNode); } else { figma.currentPage.appendChild(textNode); } return { id: textNode.id, name: textNode.name, x: textNode.x, y: textNode.y, width: textNode.width, height: textNode.height, characters: textNode.characters, fontSize: textNode.fontSize, fontWeight: fontWeight, fontColor: fontColor, fontName: textNode.fontName, fills: textNode.fills, parentId: textNode.parent ? textNode.parent.id : undefined, }; } - src/cursor_mcp_plugin/code.js:74-105 (registration)Dispatch switch statement in Figma plugin's command handler that routes 'create_text' command to the createText implementation.
return await createRectangle(params); case "create_frame": return await createFrame(params); case "create_text": return await createText(params); case "set_fill_color": return await setFillColor(params); case "set_stroke_color": return await setStrokeColor(params); case "move_node": return await moveNode(params); case "resize_node": return await resizeNode(params); case "delete_node": return await deleteNode(params); case "get_styles": return await getStyles(); case "get_local_components": return await getLocalComponents(); case "get_team_components": return await getTeamComponents(); case "create_component_instance": return await createComponentInstance(params); case "export_node_as_image": return await exportNodeAsImage(params); case "execute_code": return await executeCode(params); case "set_corner_radius": return await setCornerRadius(params); default: throw new Error(`Unknown command: ${command}`); } - src/talk_to_figma_mcp/server.ts:214-262 (registration)MCP server registration of 'create_text' tool, including input schema validation with Zod and proxy handler that forwards parameters to Figma plugin via sendCommandToFigma.
server.tool( "create_text", "Create a new text element in Figma", { x: z.number().describe("X position"), y: z.number().describe("Y position"), text: z.string().describe("Text content"), fontSize: z.number().optional().describe("Font size (default: 14)"), fontWeight: z.number().optional().describe("Font weight (e.g., 400 for Regular, 700 for Bold)"), fontColor: z.object({ r: z.number().min(0).max(1).describe("Red component (0-1)"), g: z.number().min(0).max(1).describe("Green component (0-1)"), b: z.number().min(0).max(1).describe("Blue component (0-1)"), a: z.number().min(0).max(1).optional().describe("Alpha component (0-1)") }).optional().describe("Font color in RGBA format"), name: z.string().optional().describe("Optional name for the text node by default following text"), parentId: z.string().optional().describe("Optional parent node ID to append the text to") }, async ({ x, y, text, fontSize, fontWeight, fontColor, name, parentId }) => { try { const result = await sendCommandToFigma('create_text', { x, y, text, fontSize: fontSize || 14, fontWeight: fontWeight || 400, fontColor: fontColor || { r: 0, g: 0, b: 0, a: 1 }, name: name || 'Text', parentId }); const typedResult = result as { name: string, id: string }; return { content: [ { type: "text", text: `Created text "${typedResult.name}" with ID: ${typedResult.id}` } ] }; } catch (error) { return { content: [ { type: "text", text: `Error creating text: ${error instanceof Error ? error.message : String(error)}` } ] }; } } ); - Helper function used by createText to safely set text.characters on the TextNode, handling font loading, mixed fonts with strategies (prevail, strict, experimental), and fallback to Inter Regular.
const setCharacters = async (node, characters, options) => { const fallbackFont = (options && options.fallbackFont) || { family: "Inter", style: "Regular", }; try { if (node.fontName === figma.mixed) { if (options && options.smartStrategy === "prevail") { const fontHashTree = {}; for (let i = 1; i < node.characters.length; i++) { const charFont = node.getRangeFontName(i - 1, i); const key = `${charFont.family}::${charFont.style}`; fontHashTree[key] = fontHashTree[key] ? fontHashTree[key] + 1 : 1; } const prevailedTreeItem = Object.entries(fontHashTree).sort( (a, b) => b[1] - a[1] )[0]; const [family, style] = prevailedTreeItem[0].split("::"); const prevailedFont = { family, style, }; await figma.loadFontAsync(prevailedFont); node.fontName = prevailedFont; } else if (options && options.smartStrategy === "strict") { return setCharactersWithStrictMatchFont(node, characters, fallbackFont); } else if (options && options.smartStrategy === "experimental") { return setCharactersWithSmartMatchFont(node, characters, fallbackFont); } else { const firstCharFont = node.getRangeFontName(0, 1); await figma.loadFontAsync(firstCharFont); node.fontName = firstCharFont; } } else { await figma.loadFontAsync({ family: node.fontName.family, style: node.fontName.style, }); } } catch (err) { console.warn( `Failed to load "${node.fontName["family"]} ${node.fontName["style"]}" font and replaced with fallback "${fallbackFont.family} ${fallbackFont.style}"`, err ); await figma.loadFontAsync(fallbackFont); node.fontName = fallbackFont; } try { node.characters = characters; return true; } catch (err) { console.warn(`Failed to set characters. Skipped.`, err); return false; } };