---
name: figma-mcp-setup
description: "Complete guide for installing and configuring Figma MCP Server in Devin Desktop. Covers environment checks, installation, authentication troubleshooting, and common issues based on real-world setup experience. Use this when user wants to integrate Figma with Devin AI for design-to-code workflows."
disable-model-invocation: false
---

# Figma MCP Server Setup Guide

Complete installation and configuration guide for Figma MCP Server in Devin Desktop, based on real-world troubleshooting experience.

## When to Use This Skill

Use this skill when the user wants to:
- Install Figma MCP Server for design-to-code workflows
- Integrate Figma with Devin AI
- Read Figma designs and convert them to code
- Troubleshoot Figma MCP connection issues
- Switch between different Figma accounts

## Prerequisites Checklist

### Required Software
- [ ] Devin Desktop installed (latest version recommended)
- [ ] Figma account with appropriate seat type (Full/Dev recommended)
- [ ] Stable internet connection
- [ ] Default browser configured for OAuth flow

### Required Information
- [ ] Figma account email to authenticate with
- [ ] Figma file URL with specific node-id
- [ ] Target output format (HTML/CSS, React, etc.)

### Environment Preparation
- [ ] Confirm using Devin Desktop (not Claude Code CLI)
- [ ] Logout from Figma in browser before starting
- [ ] Clear Figma cookies for fresh authentication session

## Installation Steps

### Step 1: Environment Verification

```bash
# Check if Devin Desktop is running
ps aux | grep -i devin

# Check Claude Code CLI version (for reference)
claude --version
```

**Important:** This skill is specifically for Devin Desktop. Claude Code CLI has different configuration locations and authentication methods.

### Step 2: Create Configuration Directory

```bash
mkdir -p ~/.config/devin
```

### Step 3: Create MCP Configuration File

```bash
cat > ~/.config/devin/mcp_config.json << 'EOF'
{
  "mcpServers": {
    "figma": {
      "serverUrl": "https://mcp.figma.com/mcp"
    }
  }
}
EOF
```

**Key Learning:** Config file location differs between environments:
- Devin Desktop: `~/.config/devin/mcp_config.json`
- Claude Code CLI: `~/.claude.json`
- Old Windsurf: `~/.codeium/mcp_config.json`

### Step 4: Refresh/Restart Devin Desktop

1. Open Devin Desktop
2. Navigate to Settings → Tools → Manage MCPs
3. Click Refresh button (🔄)
4. Or restart Devin Desktop completely

### Step 5: Authenticate Figma MCP

1. In Devin Desktop: Settings → Tools → Manage MCPs
2. Find the "figma" server in the list
3. Click "Authenticate" or "Connect"
4. Browser window will open automatically
5. Login with your Figma account
6. Click "Allow Access"

**Critical:** Always logout from Figma in browser and clear cookies before authenticating to avoid account caching issues.

### Step 6: Verify Authentication

```bash
# Use MCP tool to check authenticated account
mcp_call_tool whoami
```

Expected output should show your correct Figma account email and plan details.

### Step 7: Test Network Connectivity

```bash
# Test basic connectivity
curl -I https://mcp.figma.com/mcp

# Test port 443
nc -zv mcp.figma.com 443

# Test latency
ping -c 3 mcp.figma.com

# Test DNS resolution
nslookup mcp.figma.com
```

All tests should pass with no errors.

## Common Issues and Solutions

### Issue 1: "! Needs authentication" Status

**Symptoms:**
- MCP server shows "Needs authentication" status
- Cannot access Figma tools

**Solution:**
1. Verify config file exists at `~/.config/devin/mcp_config.json`
2. Refresh MCP servers in Devin Desktop
3. Authenticate through Devin Desktop interface (not CLI)
4. Check browser popup is not blocked

### Issue 2: Wrong Figma Account Authenticated

**Symptoms:**
- `whoami` shows different account than expected
- Cannot access specific Figma files

**Solution:**
1. Logout from Figma in browser completely
2. Clear all figma.com cookies from browser
3. In Devin Desktop: Disconnect and re-authenticate
4. Use incognito/private browser window if cache persists
5. Verify with `mcp_call_tool whoami` after re-authentication

### Issue 3: OAuth Session Cache Issues

**Symptoms:**
- Re-authentication keeps using same account
- Browser automatically logs in with cached credentials

**Solution:**
1. Complete browser logout from Figma
2. Clear browser cookies specifically for figma.com
3. Try different browser or incognito mode
4. Consider using browser profiles for different Figma accounts

### Issue 4: Config File Not Detected

**Symptoms:**
- Figma server doesn't appear in MCP list
- Config changes not taking effect

**Solution:**
1. Verify config file location: `~/.config/devin/mcp_config.json`
2. Check JSON syntax is valid (no trailing commas)
3. Refresh MCP servers in Devin Desktop
4. Restart Devin Desktop completely
5. Check file permissions (should be readable)

### Issue 5: File Access Denied

**Symptoms:**
- "You don't have edit access to this file"
- Permission errors when reading Figma files

**Solution:**
1. Verify your Figma account has access to the specific file
2. Check if file is in a team/workspace you're not a member of
3. Request file access from owner
4. Use `whoami` to verify authenticated account
5. Ensure file URL is valid and includes node-id

### Issue 6: Network Connectivity Issues

**Symptoms:**
- Connection timeouts
- "Failed to connect to server" errors

**Solution:**
1. Test basic connectivity: `curl -I https://mcp.figma.com/mcp`
2. Check firewall/proxy settings
3. Verify DNS resolution: `nslookup mcp.figma.com`
4. Check if port 443 is blocked
5. Test internet connection stability

## Rate Limits

Based on your Figma plan and seat type:

### Starter Plan (Your Current Plan)
- **Full/Dev Seat:** 200/day, 10/min
- **View/Collab Seat:** 20/month

### Professional Plan
- **Full/Dev Seat:** 200/day, 15/min
- **View/Collab Seat:** 6/month

### Organization Plan
- **Full/Dev Seat:** 200/day, 20/min
- **View/Collab Seat:** 6/month

### Enterprise Plan
- **Full/Dev Seat:** 600/day, 20/min
- **View/Collab Seat:** 6/month

**Exempt Tools:** `add_code_connect_map`, `create_new_file`, `whoami`

## Usage Workflow

### Reading Figma Designs

```bash
# 1. Load design-to-code guidance
mcp_read_resource skill://figma/figma-design-to-code/SKILL.md

# 2. Read Figma design context
mcp_call_tool get_design_context \
  --fileKey="FILE_KEY_FROM_URL" \
  --nodeId="NODE_ID_FROM_URL" \
  --skillNames="resource:figma-design-to-code"

# 3. Convert reference code to target stack
# Adapt the React + Tailwind output to your project's framework
```

### Extracting File Key and Node ID from URL

**URL Format:** `https://www.figma.com/design/{FILE_KEY}/{FILE_NAME}?node-id={NODE_ID}`

**Example:**
- URL: `https://www.figma.com/design/pDZFdbWxAOYiVlWDLj8UPB/BSE?node-id=87-151`
- File Key: `pDZFdbWxAOYiVlWDLj8UPB`
- Node ID: `87-151`

## Account Switching

### To Change Figma Account

1. **Check current account:** `mcp_call_tool whoami`
2. **Logout from Figma in browser**
3. **Clear Figma cookies**
4. **Disconnect in Devin Desktop:** Settings → Tools → Manage MCPs
5. **Re-authenticate** with new account
6. **Verify:** `mcp_call_tool whoami`

### Best Practices for Multiple Accounts

- Use different browser profiles for different Figma accounts
- Regularly clear Figma cookies when switching accounts
- Consider using incognito mode for authentication
- Document which account is authenticated for which project

## Troubleshooting Commands

```bash
# Check MCP server status
claude mcp list

# Add Figma MCP server
claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

# Remove MCP server
claude mcp remove figma -s user

# Check authenticated account
mcp_call_tool whoami

# Test network connectivity
curl -I https://mcp.figma.com/mcp
nc -zv mcp.figma.com 443
ping -c 3 mcp.figma.com
```

## Quick Reference

### Config File Locations
- **Devin Desktop:** `~/.config/devin/mcp_config.json`
- **Claude Code CLI:** `~/.claude.json`
- **Old Windsurf:** `~/.codeium/mcp_config.json`

### Critical Steps
1. ✅ Use correct config file location for your environment
2. ✅ Always logout from Figma browser before re-authenticating
3. ✅ Clear Figma cookies to avoid account caching
4. ✅ Authenticate through Devin Desktop UI, not CLI
5. ✅ Verify account with `whoami` after authentication
6. ✅ Test network connectivity before usage

### Common Gotchas
- ❌ Using Claude Code CLI commands for Devin Desktop setup
- ❌ Not clearing browser cache causing wrong account authentication
- ❌ Wrong config file location for environment
- ❌ Missing node-id in Figma URL
- ❌ Account without file access permissions

## Verification Checklist

After installation, verify:

- [ ] Config file exists at correct location
- [ ] Figma server appears in Devin Desktop MCP list
- [ ] Authentication shows "Connected" status
- [ ] `whoami` shows correct Figma account
- [ ] Network connectivity tests pass
- [ ] Can read Figma file with appropriate permissions
- [ ] Rate limits are understood for your plan

## Next Steps After Setup

1. **Test with a simple Figma file** to verify everything works
2. **Read design context** using `get_design_context`
3. **Convert reference code** to your target framework
4. **Implement asset handling** for images and icons
5. **Set up workflow** for regular design-to-code processes

## Additional Resources

- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
- [Devin Documentation](https://devin.ai/docs)
- [MCP Specification](https://modelcontextprotocol.io/)
- [Figma Developer Portal](https://www.figma.com/developers/api)

## Support

If issues persist after following this guide:
1. Check Figma status page for service outages
2. Verify your Figma plan and seat type
3. Check Devin Desktop logs for detailed error messages
4. Contact Figma support for account-specific issues
5. Contact Devin support for MCP integration issues

---

**Last Updated:** Based on real-world setup experience from August 2026  
**Tested On:** Devin Desktop with Figma MCP Server on macOS