Skip to content
BranchesTags

Repository files navigation

Figma-to-Elementor MCP

Convert Figma designs to Elementor v4 atomic widgets using Model Context Protocol (MCP) integration with the deployed Figma-Context-MCP server.

🎯 Features

  • ✅ Converts Figma designs to Elementor v4 widgets in ~5 seconds
  • ✅ Extracts design metadata, colors, and layout information
  • ✅ Generates production-ready Elementor JSON output
  • ✅ Integrates with deployed MCP server at https://figma-context-mcp-fre3.onrender.com

🚀 Quick Start

1. Install Dependencies

npm install

2. Run Working Conversion

node tests/successful_conversion.mjs

3. Check Output

  • test-data/figma_raw_data.yaml - Raw Figma design data
  • test-data/elementor_success_output.json - Elementor v4 compatible JSON

📋 Features

  • MCP Integration: Connects to deployed Figma-Context-MCP server
  • Session Management: Proper MCP protocol implementation with SSE support
  • Elementor v4 Support: Generates atomic widgets compatible with Elementor v4
  • Multiple Transport Modes: Supports both stdio and HTTP modes
  • Error Handling: Robust error recovery and debugging capabilities
  • TypeScript: Full TypeScript implementation with proper types

🔧 Architecture

Figma Design URL → Figma-Context-MCP → YAML Data → Elementor Widgets → JSON Output

Key Components

  1. MCP Client: Communicates with deployed Figma-Context-MCP server
  2. Session Manager: Handles MCP protocol session lifecycle
  3. YAML Parser: Extracts design data from Figma YAML response
  4. Widget Converter: Maps Figma elements to Elementor v4 widgets
  5. JSON Generator: Creates valid Elementor import format

🛠 Usage

Command Line Interface

# Stdio mode (for MCP clients like Cursor)
npx figma-to-elementor-mcp --stdio

# HTTP server mode
npx figma-to-elementor-mcp --http --port 3333

Available Tools

  1. fetch_figma_from_deployed_mcp - Fetch Figma data from deployed server
  2. convert_figma_context_to_elementor - Convert Figma data to Elementor widgets
  3. convert_figma_url_to_elementor - Complete URL-to-Elementor workflow

Example Usage

import fetch from 'node-fetch';

// Initialize MCP session
const initResponse = await fetch('https://figma-context-mcp-fre3.onrender.com/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream', // Critical!
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2024-11-05',
      capabilities: {},
      clientInfo: { name: 'figma-to-elementor', version: '1.0.0' },
    },
    id: 1,
  }),
});

const sessionId = initResponse.headers.get('mcp-session-id');

// Fetch Figma data
const figmaResponse = await fetch('https://figma-context-mcp-fre3.onrender.com/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream',
    'mcp-session-id': sessionId,
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'get_figma_data',
      arguments: {
        fileKey: 'z8nv6p3cbJCgTp7hbHXGil',
        nodeId: '645:176384',
      },
    },
    id: 2,
  }),
});

🔍 Configuration

Environment Variables

# Optional: Set custom port for HTTP mode
PORT=3333

# Optional: Set custom MCP server URL
FIGMA_MCP_URL=https://figma-context-mcp-fre3.onrender.com

MCP Client Configuration

For Cursor IDE or other MCP clients:

{
  "mcpServers": {
    "figma-to-elementor": {
      "command": "npx",
      "args": ["figma-to-elementor-mcp", "--stdio"]
    }
  }
}

📊 Output Format

Elementor v4 JSON Structure

{
  "version": "0.4",
  "title": "Figma Design Name",
  "type": "e-flexbox",
  "content": [
    {
      "id": "root_123456789",
      "elType": "widget",
      "widgetType": "e-flexbox",
      "settings": {
        "classes": {
          "$$type": "classes",
          "value": ["e-root-123456789"]
        }
      },
      "elements": [
        {
          "id": "heading_123456789",
          "elType": "widget",
          "widgetType": "e-heading",
          "settings": {
            "classes": {
              "$$type": "classes",
              "value": ["e-heading-123456789"]
            }
          },
          "editor_settings": [],
          "styles": {
            "e-heading-123456789": {
              "id": "e-heading-123456789",
              "label": "local",
              "type": "class",
              "variants": [
                {
                  "meta": {
                    "breakpoint": "desktop",
                    "state": null
                  },
                  "props": {
                    "typography": {
                      "$$type": "typography",
                      "value": {
                        "size": "32px",
                        "family": "Roboto"
                      }
                    },
                    "color": {
                      "$$type": "color",
                      "value": "#0C0D0E"
                    }
                  }
                }
              ]
            }
          }
        }
      ],
      "styles": {
        "e-root-123456789": {
          "id": "e-root-123456789",
          "label": "local",
          "type": "class",
          "variants": [
            {
              "meta": {
                "breakpoint": "desktop",
                "state": null
              },
              "props": {
                "backgroundColor": {
                  "$$type": "color",
                  "value": "#FFFFFF"
                },
                "gap": {
                  "$$type": "size",
                  "value": "20px"
                }
              }
            }
          ]
        }
      }
    }
  ]
}

🔧 Development

Build

npm run build

Development Mode

npm run dev

Testing

# Test with working solution
node tests/successful_conversion.mjs

# View test data outputs
ls test-data/

🐛 Troubleshooting

Common Issues

  1. 406 Not Acceptable Error

    Error: Failed to initialize: 406 Not Acceptable

    Solution: Ensure Accept header includes both content types:

    'Accept': 'application/json, text/event-stream'

  2. Session ID Missing

    Error: No session ID received

    Solution: Check MCP protocol version in initialization:

    protocolVersion: '2024-11-05'

  3. Parse Errors

    Error: Could not parse Figma data from response

    Solution: Handle SSE format correctly:

    const dataLine = responseText.split('\n').find(line => line.startsWith('data: '));
const jsonData = JSON.parse(dataLine.substring(6));

Debug Tools

  • Use debug_response.mjs to inspect server responses
  • Check test-data/figma_raw_data.yaml for raw Figma data
  • Verify session creation with verbose logging

🔗 Integration

Deployed MCP Server

  • URL: https://figma-context-mcp-fre3.onrender.com
  • Health Check: https://figma-context-mcp-fre3.onrender.com/health
  • Status: https://figma-context-mcp-fre3.onrender.com/api/status
  • Debug: https://figma-context-mcp-fre3.onrender.com/api/debug-figma

Figma URL Format

https://www.figma.com/design/{fileKey}/{title}?node-id={nodeId}&m=dev
  • fileKey: Extract from URL (e.g., z8nv6p3cbJCgTp7hbHXGil)
  • nodeId: Convert from URL format (e.g., 645-176384 → 645:176384)

📈 Performance

  • Session Creation: ~1-2 seconds
  • Data Fetch: ~2-3 seconds
  • Conversion: <1 second
  • Total Time: ~5 seconds

🤝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Test with successful_conversion.mjs
  4. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related Projects

📚 Documentation

function convertNodesToWidgets(nodes, metadata) { const widgets = [];

// Add a e-flexbox container for the layout widgets.push({ id: e-flexbox_${Date.now()}, elType: 'widget', widgetType: 'e-e-flexbox', settings: { gap: 'default', background_background: 'classic', background_color: '#FFFFFF', padding: { unit: 'px', top: '20', right: '20', bottom: '20', left: '20', }, }, elements: [], });

// Add an e-heading for the design name widgets[0].elements.push({ id: widget_${Date.now()}_header, elType: 'widget', widgetType: 'e-heading', settings: { title: metadata.name || 'Figma Design', header_size: 'h1', typography_typography: 'custom', typography_font_size: { unit: 'px', size: 32, }, color: '#0C0D0E', }, });

// Add widgets for each extracted node nodes.forEach((node, index) => { if (node.type === 'COLOR') { // Use e-e-flexbox for color preview (instead of div-block) widgets[0].elements.push({ id: widget_${Date.now()}_color_${index}, elType: 'widget', widgetType: 'e-e-flexbox', settings: { background_background: 'classic', background_color: node.color, width: { unit: 'px', size: 50, }, height: { unit: 'px', size: 50, }, border_radius: { unit: 'px', top: '8', right: '8', bottom: '8', left: '8', }, }, });

  // Add an e-paragraph for the color label
  widgets[0].elements.push({
    id: `widget_${Date.now()}_color_label_${index}`,
    elType: 'widget',
    widgetType: 'e-paragraph',
    settings: {
      text: `Color: ${node.color}`,
      typography_typography: 'custom',
      typography_font_size: {
        unit: 'px',
        size: 14,
      },
      color: '#69727D',
    },
  });
} else {
  // Add an e-paragraph for generic nodes
  widgets[0].elements.push({
    id: `widget_${Date.now()}_node_${index}`,
    elType: 'widget',
    widgetType: 'e-paragraph',
    settings: {
      text: `Node: ${node.name}`,
      typography_typography: 'custom',
      typography_font_size: {
        unit: 'px',
        size: 16,
      },
      color: '#0C0D0E',
    },
  });
}

});

return widgets; }

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity

Stars

3 stars

Watchers

2 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages