# 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]