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

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

2. Configure Figma Token

Create a .env file in the root directory:

FIGMA_TOKEN=your_personal_access_token_here

Getting Your Token:

1. Go to Figma Account 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

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

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

With VS Code MCP

Add to .vscode/mcp.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

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

npx tsx tests/test-tool.ts

Generates output/output.html with complete HTML/CSS from a Figma design.

Test Enhanced Generation with Screenshot

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

npx tsx tests/test-image.ts

Downloads a screenshot as output/figma-screenshot-{nodeId}.png

Test Token Validation

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

# 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 - Common issues and fixes
• CSS-IMPROVEMENTS.md - CSS generation details
• 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 for more solutions.

🔒 Security

• ⚠️ Never commit .env - Contains your Figma token
• ✅ Use environment variables for all secrets
• 🔐 For production, follow MCP Authorization Best Practices

🌟 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
• MCP TypeScript SDK
• Figma API Documentation

📄 License

MIT

---

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