README.md•8.31 kB
# Figma MCP Tool
English | [简体中文](README.zh-CN.md)
A Model Context Protocol (MCP) server that integrates with the Figma API to export images and extract style data.
## Features
- 🖼️ **Image export**: Export node images from a Figma URL; supports PNG, JPG, SVG, PDF
- 🎨 **Style extraction**: Fetch detailed style data for design elements; supports CSS generation
- 📦 **Batch export**: Export multiple nodes in one go
- 🔄 **Smart retry**: Built-in retry to handle network hiccups and API limits
- 🛡️ **Robust errors**: Clear error handling and troubleshooting guidance
- 🧩 **Design element analysis**: Deeply analyze images, vectors, components in designs 🆕
- 📋 **SVG extraction**: Get SVG code for vector graphics directly 🆕
## Install and Run
### Option 1: Run via npx (recommended, no install)
```bash
npx figma-mcp-full-server figd_your_figma_token_here
```
### Option 2: Global install
```bash
# Install globally
npm install -g figma-mcp-full-server
# Run
figma-mcp-full-server figd_your_figma_token_here
```
### Option 3: Local project install
```bash
# Install in your project
npm install figma-mcp-full-server
# Run
npx figma-mcp-full-server figd_your_figma_token_here
# or
node_modules/.bin/figma-mcp-full-server figd_your_figma_token_here
```
### Option 4: Run from source (for development)
```bash
git clone <repository>
cd figma-mcp
npm install
npm run build
# Run
npm start figd_your_figma_token_here
# or
node build/index.js figd_your_figma_token_here
```
## Quick Start
### 1. Get a Figma access token
1. Log in to [Figma](https://figma.com)
2. Open Settings
3. Find the "Personal access tokens" section
4. Click "Create new token"
5. Copy the token (starts with `figd_`)
### 2. Configure in Claude Desktop
Edit the Claude config file (pick your OS):
macOS/Linux: `~/.config/claude-desktop/config.json`
Windows: `%APPDATA%\Claude Desktop\config.json`
Choose one of the following setups:
#### Setup A: Run via npx (recommended)
```json
{
"mcpServers": {
"figma-mcp-full-server": {
"command": "npx",
"args": ["figma-mcp-full-server"],
"env": {
"FIGMA_TOKEN": "figd_your_figma_token_here"
}
}
}
}
```
#### Setup B: Global install
```bash
npm install -g figma-mcp-full-server
```
```json
{
"mcpServers": {
"figma-mcp-full-server": {
"command": "figma-mcp-full-server",
"env": {
"FIGMA_TOKEN": "figd_your_figma_token_here"
}
}
}
}
```
#### Setup C: Use from a project
```bash
npm install figma-mcp-full-server
```
```json
{
"mcpServers": {
"figma-mcp-full-server": {
"command": "npx",
"args": ["figma-mcp-full-server"],
"cwd": "/path/to/your/project",
"env": {
"FIGMA_TOKEN": "figd_your_figma_token_here"
}
}
}
}
```
#### Setup D: Run from source
```json
{
"mcpServers": {
"figma-mcp": {
"command": "node",
"args": [
"/absolute/path/to/figma-mcp/build/index.js"
],
"cwd": "/absolute/path/to/figma-mcp",
"env": {
"FIGMA_TOKEN": "figd_your_figma_token_here"
}
}
}
}
```
⚠️ Notes:
- Recommended: Setup A (npx) — no install, always latest
- Global install: good if you use it often
- Project install: pin a version per project
- From source: for development and customization
- Replace `figd_your_figma_token_here` with your real Figma token
### 3. Restart Claude Desktop
Restart Claude Desktop to apply the config.
## Usage
Once configured, use it directly in Claude:
### Get Figma images
```
Please fetch images from this Figma URL:
https://www.figma.com/design/EXAMPLE_FILE_ID/Design-Name?node-id=123-456&t=abc123-0
```
### Get style data and generate CSS
```
Please get style data from this design and generate CSS:
https://www.figma.com/design/EXAMPLE_FILE_ID/Design-Name?node-id=123-456&t=abc123-0
```
### Get file info
```
Please show the basic info for this Figma file:
https://www.figma.com/design/EXAMPLE_FILE_ID/Design-Name
```
### Get design elements 🆕
```
Please analyze what design elements this Figma node contains:
https://www.figma.com/design/EXAMPLE_FILE_ID/Design-Name?node-id=123-456&t=abc123-0
```
### Get image assets 🆕
```
Please extract all image assets under this Figma node:
https://www.figma.com/design/EXAMPLE_FILE_ID/Design-Name?node-id=123-456&t=abc123-0
```
### Get SVG data 🆕
```
Please get the SVG code for this Figma node:
https://www.figma.com/design/EXAMPLE_FILE_ID/Design-Name?node-id=123-456&t=abc123-0
```
## Available Tools
This MCP server provides 7 tools:
### Basics
1. **get_figma_image** — Get node image by Figma URL
2. **get_figma_styles** — Get node style data; optional CSS output
3. **export_multiple_images** — Batch export multiple nodes
4. **get_file_info** — Get basic file info
### Design element tools 🆕
5. **get_node_images** — Get all image assets under a node
6. **get_node_svg** — Get SVG data for a node
7. **extract_node_elements** — Extract all design elements (images, vectors, components)
## Troubleshooting
### Common issues
#### 1. "Cannot find module"
- Cause: Using a `.ts` entry instead of the built `.js`
- Fix: Use `/path/to/build/index.js` instead of `index.ts`
#### 2. "Access denied"
- Cause: Invalid Figma token or insufficient file permission
- Fix: Verify token, ensure file is public or accessible
#### 3. MCP server won’t start
- Cause: Wrong paths or Node.js version too low
- Fix:
- Use absolute paths
- Ensure Node.js ≥ 18
- Rebuild: `npm run build`
#### 4. "No exportable images found"
- Cause: URL missing `node-id` parameter
- Fix: Ensure URL includes `?node-id=xxxxx-xxxxx`
### Manual test
```bash
cd /path/to/figma-mcp
node build/index.js figd_your_token_here
```
You should see: `Figma MCP server started`
### Validate config
```bash
# macOS/Linux
cat ~/.config/claude-desktop/config.json | python -m json.tool
# Windows
type "%APPDATA%\Claude Desktop\config.json" | python -m json.tool
```
## Technical Details
### Smart retry
- Handles transient network issues automatically
- Exponential backoff
- Error classification and recovery
### Batch processing
- Automatically splits large node sets (90 per batch)
- Avoids URL length limits
- Concurrency control and resource management
### Error handling
- Detailed messages and remediation tips
- Friendly feedback
- Complete logging
## Development
### Dev mode
```bash
npm run dev
# Then set FIGMA_TOKEN in your environment
```
### Project structure
```
figma-mcp/
├── src/
│ ├── index.ts # MCP server entry
│ ├── figma-service.ts # Figma API service
│ ├── image-extractor.ts # Image export
│ ├── style-extractor.ts # Style extraction
│ └── element-extractor.ts # Design element extraction 🆕
├── build/ # Build output
├── package.json
└── README.md
```
## New Features 🆕
### Design element analysis
- **Image asset recognition**: Find all images, including embedded and external
- **Vector extraction**: Extract SVG paths, shapes, icons
- **Component analysis**: Identify components and instances
- **Hierarchy traversal**: Deeply walk the node tree
### SVG data
- **Full SVG export**: Complete SVG code with styles and paths
- **Vector fidelity**: Preserve vector properties for lossless scaling
- **Inline styles**: SVG contains complete styles, ready to use
### Smart element detection
- **Auto categorization**: Images, vectors, text, components
- **De-duplication**: Remove duplicate resource references
- **Detail control**: Overview vs detailed output modes
## Security Best Practices
1. **Token safety**: Use env vars for the Figma token; never hardcode
2. **Access control**: Rotate tokens regularly
3. **Least privilege**: Grant the minimum required file access
## License
MIT License
---
## Support
If you run into issues:
1. Ensure Node.js ≥ 18
2. Verify your Figma token
3. Validate your JSON config
4. Check Claude Desktop logs
5. Manually start the MCP server
Once configured, you can use Figma files directly in Claude!
### Contact
<img src="contact.JPG" alt="Contact" width="360" />
<img src="程序员热榜.jpg" alt="程序员热榜公众号" width="360" />
