npm package: @rui.branco/figma-mcp
Description: Figma MCP server for Claude Code - fetch designs, export frames, and view specs
Author: Rui Branco
Latest version: 1.0.2

# Figma MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that brings Figma designs directly into Claude Code. View design specifications, export frames as images, and reference visual context without leaving your development environment.

## Overview

Implementing designs accurately requires constant reference to Figma. This MCP server eliminates context switching by:

- **Fetching design information** - Get file names, frame details, and dimensions
- **Exporting images** - Download frames as high-resolution PNGs
- **Smart section splitting** - Large frames are automatically split into readable sections
- **Seamless integration** - Works standalone or integrated with [jira-mcp](https://github.com/rui-branco/jira-mcp)

## Features

| Feature | Description |
|---------|-------------|
| Design Info | File name, last modified, frame dimensions |
| Image Export | Export frames as PNG, SVG, JPG, or PDF |
| Auto-Scaling | 2x scale by default for retina clarity |
| Section Detection | Large frames split into individual sections |
| Batch Export | Export multiple frames efficiently |
| URL Parsing | Supports file, design, and prototype URLs |

## Installation

### Prerequisites

- Node.js 18+
- [Claude Code](https://claude.ai/code) CLI
- Figma account with API access

### Step 1: Add to Claude Code

```bash
claude mcp add --transport stdio figma -- npx -y @rui.branco/figma-mcp
```

### Step 2: Get Your Figma Token

1. Go to [Figma Account Settings](https://www.figma.com/settings)
2. Scroll down to **"Personal access tokens"**
3. Click **"Generate new token"**
4. Enter a description (e.g., "Claude Code MCP")
5. Click **"Generate token"**
6. Copy the token (you won't be able to see it again)

### Step 3: Configure Credentials

Run the setup with your token:

```bash
npx @rui.branco/figma-mcp setup "YOUR_FIGMA_TOKEN"
```

Or run interactively (will prompt for the token):

```bash
npx @rui.branco/figma-mcp setup
```

### Step 4: Verify

Restart Claude Code and run `/mcp` to verify the server is connected.

### Alternative: Manual Installation

If you prefer to install manually:

```bash
git clone https://github.com/rui-branco/figma-mcp.git ~/.config/figma-mcp
cd ~/.config/figma-mcp && npm install
node setup.js
```

Then add to Claude Code:

```bash
claude mcp add --transport stdio figma -- node $HOME/.config/figma-mcp/index.js
```

## Usage

### Fetch a Design

```
> Get this Figma design: https://www.figma.com/design/ABC123/MyProject?node-id=1-234
```

### Example Output

```
# Figma File: MyProject

**Last Modified:** 2025-01-15T10:30:00Z

## Selected Frame: Login Screen

**Type:** FRAME
**Size:** 1440 x 900

### Sections (4):
- **Header** (FRAME, 1440x80)
- **Login Form** (FRAME, 400x350)
- **Footer** (FRAME, 1440x60)
- **Background** (FRAME, 1440x900)

### Exported Sections:
- Header: ~/.config/figma-mcp/exports/ABC123_1_234.png
- Login Form: ~/.config/figma-mcp/exports/ABC123_1_235.png
- Footer: ~/.config/figma-mcp/exports/ABC123_1_236.png

[Images displayed inline]
```

## Smart Section Export

For large frames (>1500px wide or >2000px tall), the server automatically:

1. Detects child frames, components, and groups
2. Exports each section separately at 2x scale
3. Provides better detail than a single compressed image
4. Limits to 10 sections by default (configurable)

This is especially useful for:
- Full-page designs with multiple sections
- Component libraries
- Design system documentation

## API Reference

### Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `figma_get_design` | Fetch design from URL | `url` (required), `exportImage`, `exportChildren`, `maxChildren`, `scale` |
| `figma_export_frame` | Export specific frame | `fileKey`, `nodeId` (required), `format`, `scale` |

### Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `exportImage` | `true` | Export images |
| `exportChildren` | `true` | Split large frames into sections |
| `maxChildren` | `10` | Maximum sections to export |
| `scale` | `2` | Export scale (1-4) |
| `format` | `png` | Export format (png, svg, jpg, pdf) |

### Configuration

Config stored at `~/.config/figma-mcp/config.json`:

```json
{
  "token": "YOUR_FIGMA_TOKEN"
}
```

## Error Handling

The server provides clear error messages:

| Error | Meaning | Solution |
|-------|---------|----------|
| `Rate limit exceeded` | Too many API requests | Wait a few minutes |
| `Access denied` | Invalid token or no file access | Check token permissions |
| `File not found` | Invalid URL or deleted file | Verify the Figma URL |

## Integration with Jira MCP

When used alongside [jira-mcp](https://github.com/rui-branco/jira-mcp):

1. Figma links in Jira tickets are **automatically detected**
2. Designs are **fetched without manual intervention**
3. Images appear **inline with ticket context**

This creates a seamless workflow:
```
> Get ticket PROJ-123

# Returns ticket details + auto-fetched Figma designs
```

## Security

- Tokens stored locally in `~/.config/figma-mcp/config.json`
- Config excluded from git via `.gitignore`
- Tokens only transmitted to Figma API
- Exports saved to `~/.config/figma-mcp/exports/`

## License

MIT

## Related

- [jira-mcp](https://github.com/rui-branco/jira-mcp) - Jira MCP server with Figma integration
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
- [Figma API](https://www.figma.com/developers/api) - Figma REST API documentation