ForgeKit Figma MCP

The bridge between Figma and your Codebase.

ForgeKit is a powerful CLI tool and MCP Server that syncs Figma variables (design tokens) directly into your project. It supports multiple frameworks, handles complex alias resolution, and manages light/dark modes automatically.

🚀 Why ForgeKit?

• Universal Support: Works with Chakra UI (v2 & v3), Shadcn/Tailwind, and generates Documentation.
• Smart Onboarding: Just paste your Figma URL. ForgeKit detects your framework and sets everything up.
• Starter Kits: Don't have a design system? ForgeKit provides starter files for Chakra and Shadcn.
• Semantic Tokens: Automatically maps Figma Modes (Light/Dark) to CSS variables or theme objects.
• Secure: Automatically manages your FIGMA_ACCESS_TOKEN in .env and adds it to .gitignore.

📦 Installation

npm install forgekit-figma-mcp

⚡ Quick Start

The easiest way to get started is with the interactive init command.

1. Initialize

npx forgekit init

What happens next?

1. Paste your Figma URL: You don't need to find the File ID. Just paste the whole link.
   • Tip: If you provide a URL, ForgeKit will analyze it and auto-select the correct framework for you.
2. Enter your Token: If you don't have one, we'll guide you. It's saved securely to .env.
3. Choose Outputs: Select one or more:
   • Chakra UI v3 (New createSystem format)
   • Chakra UI v2 (Classic extendTheme)
   • Shadcn/Tailwind (Generates globals.css vars & config)
   • Documentation (Markdown & JSON)

2. Sync

Once configured, run this command whenever your design team updates Figma:

npx forgekit sync

Your theme files, CSS variables, and documentation are now up to date!

🎨 Supported Frameworks

Shadcn UI / Tailwind CSS

ForgeKit generates the CSS variables required for Shadcn's theming system.

Output:

• globals.css: Contains :root and .dark variables (e.g., --primary, --muted-foreground).
• tailwind.theme.json: A config snippet you can import into tailwind.config.ts.

Configuration:

{
  "format": "shadcn",
  "dir": "./src/theme",
  "cssPath": "./src/app/globals.css"
}

Chakra UI v3

Generates the modern createSystem configuration.

Output:

• tokens.ts: Primitive tokens (colors, spacing).
• semanticTokens.ts: Mode-aware tokens.
• index.ts: Exports the system object.

Chakra UI v2

Generates the classic extendTheme object.

Output:

• colors.ts, space.ts, etc.
• index.ts: Exports the theme object.

Documentation

Perfect for Storybook or internal documentation sites.

Output:

• tokens.md: A visual Markdown representation of your colors, spacing, and radii.
• tokens.json: The raw token data for building custom views.

⚙️ Configuration (forgekit.json)

You can handle complex setups (like sourcing different tokens from different files) using the configuration file.

{
  // Global source file (optional if overridden below)
  "figmaFileId": "12345abcdef...", 
  
  "outputs": [
    { 
      "format": "chakra-v3", 
      "dir": "./src/theme" 
    },
    { 
      "format": "shadcn", 
      "dir": "./src/theme",
      "cssPath": "./src/app/globals.css",
      // Optional: Source Shadcn tokens from a specific file
      "figmaFileId": "98765zyxw..." 
    },
    { 
      "format": "docs", 
      "dir": "./docs/design-system" 
    }
  ]
}

🤖 MCP Server Usage

ForgeKit is also a Model Context Protocol (MCP) server. This allows AI assistants (like Cursor or Claude Desktop) to directly interact with your design system.

Add this to your MCP client configuration:

{
  "mcpServers": {
    "forgekit": {
      "command": "npx",
      "args": ["forgekit-figma-mcp"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your_figma_access_token"
      }
    }
  }
}

What can the AI do?

• "Sync my design tokens."
• "Check if the code matches the Figma design."
• "Generate a new component using the latest tokens."

🛠 CLI Reference

| Command | Description | | :--- | :--- | | npx forgekit init [url] | Interactive setup. Optionally pass a Figma URL to auto-detect settings. | | npx forgekit sync | Fetch tokens and generate files based on forgekit.json. |

Sync Arguments (Overrides config):

| Flag | Description | | :--- | :--- | | --token <token> | Figma Personal Access Token | | --file-id <id> | Figma File ID or URL | | --out <dir> | Output directory (Legacy single-mode) | | --framework <name> | chakra, chakra-v3 (Legacy single-mode) |

🤝 Contributing

1. Clone the repo
2. Install dependencies: npm install
3. Build: npm run build
4. Run locally: node dist/cli.js init

License

MIT