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

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