Figma i18n MCP Server

A Model Context Protocol (MCP) server that extracts text from Figma designs for internationalization (i18n). This tool automatically extracts all visible text nodes from Figma files and organizes them into a structured JSON format, grouped by frames and components, perfect for translation workflows.

Features

• 🎨 Extract text from any Figma file or specific frame

• 🔑 Automatically generate i18n keys for each text node

• 📦 Group text by frames and components

• 🚫 Skip invisible/hidden layers

• 🌳 Nested JSON output ready for i18n libraries

Prerequisites

• Node.js (v18 or higher recommended)

• Figma Access Token (see setup instructions below)

• Claude Desktop or any MCP-compatible client

Installation

1. Clone or download this repository:

   git clone <your-repo-url> cd i18n-figma-mcp

2. Install dependencies:

   npm install

3. Get your Figma Access Token:

   • Log in to Figma

   • Go to Settings → Account → Personal Access Tokens

   • Click Generate new token

   • Give it a name (e.g., "MCP i18n Extractor")

   • Copy the token immediately (you won't see it again!)

Configuration

Claude Desktop Setup

1. Locate your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this MCP server to the config:

   { "mcpServers": { "figma-i18n": { "command": "node", "args": [ "/absolute/path/to/i18n-figma-mcp/src/index.js" ], "cwd": "/absolute/path/to/i18n-figma-mcp", "env": { "FIGMA_TOKEN": "your-figma-access-token-here" } } } }

3. Replace the placeholders:

   • Replace /absolute/path/to/i18n-figma-mcp with the actual full path to this project

   • Replace your-figma-access-token-here with your Figma access token

4. Restart Claude Desktop to load the new MCP server

Usage

Once configured, you can use the extract_figma_i18n tool in Claude Desktop:

Example Prompts:

Extract from a Figma file:

Extract from a specific frame:

Output Format

The tool returns a nested JSON structure grouped by frames:

How It Works

1. Parses the Figma URL to extract file key and optional node ID

2. Fetches the design data using the Figma API

3. Traverses the component tree recursively

4. Extracts visible text nodes with their frame/component context

5. Generates unique keys for each text entry

6. Returns structured JSON ready for translation

Troubleshooting

"Invalid Figma URL" error

• Ensure you're using a valid Figma file or frame URL

• Format: https://www.figma.com/file/{fileKey}/... or https://www.figma.com/design/{fileKey}/...

"Authentication failed" or API errors

• Verify your Figma access token is correct

• Check that the token has read access to the file

• Ensure the file is accessible with your Figma account

Server not appearing in Claude Desktop

• Verify the config file path is correct

• Check that all paths in the config are absolute paths

• Restart Claude Desktop after making changes

• Check Claude Desktop logs for error messages

Empty results

• Make sure the Figma file contains visible text nodes

• Verify you have permission to access the file

• Try using a specific frame URL if the file is very large

Development

To run the server locally for testing:

The server communicates via stdio and expects JSON-RPC messages following the MCP protocol.

Version

Current version: 1.1.0

License

[Your License Here]