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