Figma MCP Server

# 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**