# 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:**
```bash
git clone <your-repo-url>
cd i18n-figma-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Get your Figma Access Token:**
- Log in to [Figma](https://www.figma.com)
- 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:**
```json
{
"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 i18n text from this Figma file: https://www.figma.com/file/ABC123xyz/MyDesign
```
**Extract from a specific frame:**
```
Extract text from this Figma frame: https://www.figma.com/file/ABC123xyz/MyDesign?node-id=123-456
```
### Output Format
The tool returns a nested JSON structure grouped by frames:
```json
{
"login_screen": {
"welcome_message": "Welcome back!",
"email_placeholder": "Enter your email",
"password_placeholder": "Password",
"login_button": "Sign In"
},
"dashboard": {
"title": "Dashboard",
"subtitle": "Your overview"
}
}
```
## 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:
```bash
npm start
```
The server communicates via stdio and expects JSON-RPC messages following the MCP protocol.
## Version
Current version: 1.1.0
## License
[Your License Here]
