# Figma MCP Server

A powerful MCP (Model Context Protocol) server that connects AI applications to the Figma API, enabling seamless access to Figma designs, automatic HTML/CSS generation, and screenshot capture.

## 🚀 Features

### Available MCP Tools

| Tool | Description | Use Case |
|------|-------------|----------|
| **getFile** | Fetch complete Figma file data | Get entire file structure and metadata |
| **getNode** | Fetch specific node from a file | Access individual components or frames |
| **analyzeDesign** | Extract and analyze design properties | Understand component structure and styling |
| **generateCSS** | Generate CSS from Figma nodes | Convert Figma styles to CSS code |
| **generateHTML** | Generate HTML structure | Create semantic HTML from designs |
| **generateFullDesign** | Generate complete HTML/CSS file | Convert entire designs to working code |
| **getImage** | Capture screenshots/renders | Export designs as PNG, JPG, SVG, or PDF |
| **generateDesignWithScreenshot** | Generate HTML/CSS with screenshot reference | More accurate design-to-code with visual context |
| **generateBootstrapDesign** ⭐ | Generate Bootstrap 5 + SCSS from Figma | Production-ready responsive designs |

### What You Can Do

- 📊 **Extract Design Data** - Access complete design specifications
- 🎨 **Generate CSS** - Convert Figma styles to production-ready CSS
- 🏗️ **Create HTML** - Generate semantic HTML structure from designs
- 📸 **Capture Screenshots** - Export designs as images in multiple formats
- 🔍 **Analyze Components** - Understand design properties and hierarchy
- ⚡ **Automate Workflows** - Integrate with AI tools like Claude Desktop
- 🚀 **Bootstrap Integration** ⭐ NEW - Generate responsive designs with Bootstrap 5 + SCSS

## 📋 Prerequisites

- **Node.js** v17 or higher
- **Figma Personal Access Token** (not a file access token)

## 🛠️ Installation

### 1. Clone and Install

```bash
git clone <your-repo-url>
cd figma-mcp
npm install
```

### 2. Configure Figma Token

Create a `.env` file in the root directory:

```bash
FIGMA_TOKEN=your_personal_access_token_here
```

**Getting Your Token:**
1. Go to [Figma Account Settings](https://www.figma.com/settings)
2. Scroll to "Personal access tokens"
3. Click "Create a new personal access token"
4. Copy the token and add it to `.env`

⚠️ **Important:** Use a **Personal Access Token**, not a file-specific token.

### 3. Build the Project

```bash
npm run build
```

## 🎯 Usage

### With Claude Desktop

Add to your Claude config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["C:\\path\\to\\figma-mcp\\build\\index.js"]
    }
  }
}
```

### With VS Code MCP

Add to `.vscode/mcp.json`:

```json
{
  "servers": {
    "figma-mcp-server": {
      "type": "stdio",
      "command": "npm",
      "args": ["start"]
    }
  }
}
```

## 📖 Tool Usage Examples

### Understanding Figma URLs

For a URL like:
```
https://www.figma.com/design/YwUqmarhRx74Gb4zePtEUx/My-Design?node-id=8384-4
```

- **File Key**: `YwUqmarhRx74Gb4zePtEUx`
- **Node ID**: `8384-4` (or `8384:4` - both formats work)

### 1. Analyze Design Structure

```
Use analyzeDesign with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
```

Returns detailed design properties including:
- Component hierarchy
- Colors and fills
- Typography settings
- Dimensions and positioning

### 2. Generate CSS Styles

```
Use generateCSS with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
- className: .my-component (optional)
```

Generates production-ready CSS with:
- Colors (rgba format)
- Typography (font-family, size, weight)
- Layout (width, height, padding)
- Effects (shadows, borders, border-radius)

### 3. Generate HTML Structure

```
Use generateHTML with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
```

Creates semantic HTML structure matching your Figma hierarchy.

### 4. Generate Complete HTML/CSS Page

```
Use generateFullDesign with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
```

Generates a complete HTML file with:
- Inline CSS styles
- Semantic HTML structure
- Responsive reset styles
- Proper typography and spacing

### 5. Capture Screenshots/Images

```
Use getImage with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
- format: png (or jpg, svg, pdf)
- scale: 2 (optional, 0.01 to 4)
```

**Format Guide:**
- **PNG** - Best for UI designs with transparency (recommended)
- **JPG** - Smaller file size, no transparency
- **SVG** - Vector format, scalable
- **PDF** - Print-ready documents

**Scale Options:**
- `1` - Original size (default)
- `2` - Retina/HiDPI displays (recommended)
- `3-4` - Very high resolution (print quality)
- `0.01-0.99` - Thumbnails/previews

Returns a temporary download URL (valid ~30 minutes).

### 6. Generate Design with Screenshot Reference (Enhanced) ⭐

```
Use generateDesignWithScreenshot with:
- fileKey: YwUqmarhRx74Gb4zePtEUx
- nodeId: 8384-4
- includeScreenshot: true (optional, default true)
```

**What makes this special:**
This tool combines both the Figma API data AND a screenshot of the actual design to give you more accurate HTML/CSS generation.

**Benefits:**
- 📸 **Visual Reference** - Screenshot URL included in CSS comments
- 🎯 **More Accurate** - Generate code with visual context
- 💡 **Better Guidance** - Comments suggest how to match the screenshot
- 🔄 **Side-by-side Comparison** - Easily compare output with original

**Perfect for:**
- Pixel-perfect implementations
- Complex layouts requiring visual verification
- When you want to ensure design fidelity
- Learning how designs translate to code

## 🧪 Testing Tools

Run test scripts from the `tests/` directory. **All outputs are saved to the `output/` folder.**

### Test Bootstrap-Enhanced Generation 🚀 RECOMMENDED
```bash
npx tsx tests/test-bootstrap-enhanced.ts
```
Generates production-ready designs with:
- ✅ Bootstrap 5 framework included
- ✅ SCSS source files (editable)
- ✅ Compiled CSS embedded in HTML
- ✅ Semantic class names from Figma
- ✅ Screenshot reference for comparison
- ✅ Responsive, mobile-first layout

**Output:** `output/{component-name}.html`, `output/{component-name}.scss`, `output/{component-name}-screenshot.png`

**Why use this?** Generates designs that actually look like the screenshot!

### Test HTML/CSS Generation
```bash
npx tsx tests/test-tool.ts
```
Generates `output/output.html` with complete HTML/CSS from a Figma design.

### Test Enhanced Generation with Screenshot
```bash
npx tsx tests/test-screenshot-enhanced.ts
```
Generates `output/output-with-screenshot.html` AND downloads a reference screenshot to `output/screenshot-{nodeId}.png`. The HTML includes comments with the screenshot path for easy comparison.

### Test Image Capture
```bash
npx tsx tests/test-image.ts
```
Downloads a screenshot as `output/figma-screenshot-{nodeId}.png`

### Test Token Validation
```bash
npx tsx tests/test-token.ts
```
Validates your Figma API token and permissions.

## 🏗️ Project Structure

```
figma-mcp/
├── src/
│   └── index.ts                     # Main MCP server implementation
├── tests/
│   ├── test-bootstrap-enhanced.ts   # 🚀 Bootstrap + SCSS generation (RECOMMENDED)
│   ├── test-tool.ts                 # HTML/CSS generation test
│   ├── test-screenshot-enhanced.ts  # Enhanced generation with screenshot
│   ├── test-image.ts                # Image capture test
│   ├── test-token.ts                # Token validation test
│   └── README.md                    # Test documentation
├── output/                          # Generated HTML/CSS and screenshots
│   ├── .gitignore                   # Ignores generated files
│   └── README.md                    # Output folder guide
├── docs/
│   ├── TROUBLESHOOTING.md           # Common issues and solutions
│   ├── CSS-IMPROVEMENTS.md          # CSS generation details
│   ├── IMAGE-FEATURE.md             # Screenshot feature guide
│   ├── SCREENSHOT-ENHANCED.md       # Enhanced generation guide
│   ├── BOOTSTRAP-ENHANCED.md        # 🚀 Bootstrap + SCSS guide (NEW)
│   └── README.md                    # Documentation index
├── build/                           # Compiled JavaScript output
├── .env                             # Environment variables (not in git)
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
```

## 🔧 Development

### Build Commands

```bash
# Build once
npm run build

# Build and watch for changes
npm run build -- --watch

# Start the server
npm start
```

### Supported Figma Properties

**Layout:**
- Width, height, positioning
- Padding and margins
- Border radius

**Typography:**
- Font family, size, weight
- Line height, text alignment
- Text content

**Colors:**
- Fill colors (solid, gradients)
- Stroke/border colors
- Opacity/transparency

**Effects:**
- Drop shadows
- Box shadows
- Border styles

## 📚 Documentation

- **[TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md)** - Common issues and fixes
- **[CSS-IMPROVEMENTS.md](./docs/CSS-IMPROVEMENTS.md)** - CSS generation details
- **[IMAGE-FEATURE.md](./docs/IMAGE-FEATURE.md)** - Screenshot capabilities

## 🐛 Troubleshooting

### "Invalid token" Error

✅ **Solution:** Use a Personal Access Token, not a file access token
- Go to Figma Settings → Personal access tokens
- Create a new token with full API access
- Update your `.env` file

### Node Not Found

✅ **Solution:** Check node ID format
- Both `8384-4` and `8384:4` work
- Get node ID from Figma URL or inspect panel

### Class Names Not Working

✅ **Solution:** Already fixed in latest version
- Class names are normalized (colons → dashes)
- CSS selectors are valid

See [docs/TROUBLESHOOTING.md](./docs/TROUBLESHOOTING.md) for more solutions.

## 🔒 Security

- ⚠️ **Never commit `.env`** - Contains your Figma token
- ✅ Use environment variables for all secrets
- 🔐 For production, follow [MCP Authorization Best Practices](https://modelcontextprotocol.io/docs/tutorials/security/authorization)

## 🌟 Use Cases

1. **Design-to-Code** - Convert Figma designs to HTML/CSS automatically
2. **Design Systems** - Extract component styles for documentation
3. **Asset Export** - Batch export design elements as images
4. **Design Review** - Capture screenshots for presentations
5. **AI Integration** - Connect Figma to AI tools via MCP
6. **Automation** - Build workflows with Figma data

## 📖 References

- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Figma API Documentation](https://www.figma.com/developers/api)

## 📄 License

MIT

---

**Made with ❤️ for the design-to-code community**