flowbite-mcp 1.0.0 → 1.1.0

package/README.md

@@ -12,17 +12,23 @@
     <a href="https://flowbite.com/docs/getting-started/license/"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License"></a>
 </p>
 
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=flowbite&config=eyJlbnYiOnsiRklHTUFfQUNDRVNTX1RPS0VOIjoiWU9VUl9QRVJTT05BTF9GSUdNQV9BQ0NFU1NfVE9LRU4ifSwiY29tbWFuZCI6Im5weCAteSBmbG93Yml0ZS1tY3AifQ%3D%3D)
+
 An MCP server that enables AI assistants to access the [Flowbite](https://flowbite.com/) library of Tailwind CSS components—including UI elements, forms, typography, and plugins—while offering an intelligent theme generator for creating custom branded designs within AI-driven development environments.
 
 ## MCP Features
 
-- **🎨 60+ UI Components** - Complete access to buttons, cards, modals, dropdowns, and more
-- **📝 Form Elements** - Input fields, checkboxes, radio buttons, select, textarea, and advanced form components
-- **✍️ Typography Components** - Headings, paragraphs, blockquotes, lists, and text styling
-- **🔌 Plugin Integrations** - Charts, datatables, WYSIWYG editors, and datepickers
-- **🎯 AI-Powered Theme Generator** - Create custom branded themes from any hex color
-- **📦 Component Source Code** - Latest Flowbite Tailwind CSS implementations
-- **📋 Metadata Access** - Component descriptions, usage patterns, and integration guides
+### Resources:
+
+- **📦 60+ UI Components** - Complete access the [Flowbite Library](https://flowbite.com/docs/getting-started/introduction/) components of buttons, cards, modals, dropdowns, and more
+
+### Tools:
+
+- **🎯 AI-Powered Theme Generator** - Create custom branded themes from any branded hex color
+- **🎨 [NEW] Figma to Code Generator** - Copy the Figma node url and generate code ([video demo](https://x.com/zoltanszogyenyi/status/1996953610966405547))
+
+### Server:
+
 - **🌐 Dual Transport Support** - Standard I/O (stdio) for CLI or HTTP Streamable for server deployments
 - **⚡ Production Ready** - Docker support with health checks and monitoring
 - **🎨 Quickstart Guide** - Complete setup and integration documentation
@@ -44,7 +50,7 @@ npx flowbite-mcp --help
 npx flowbite-mcp --mode http --port 3000
 ```
 
-## Transport Modes
+## Local Transport Modes
 
 ### Standard I/O (stdio)
 
@@ -54,17 +60,22 @@ The default mode for local development and CLI integrations:
 # Start in stdio mode (default)
 node build/index.js
 
-# Configure in Claude Desktop config.json
+# Configure in MCP client (ie. Cursor, Windsurf, Claude)
 {
   "mcpServers": {
     "flowbite": {
       "command": "node",
-      "args": ["/path/to/flowbite-mcp/build/index.js"]
+      "args": ["/path/to/flowbite-mcp/build/index.js"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "YOUR_PERSONAL_FIGMA_ACCESS_TOKEN"
+      }
     }
   }
 }
 ```
 
+Learn how to get the [Figma personal access token](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) to enable the Figma to code generation tool.
+
 ### HTTP server
 
 HTTP-based transport for production and multi-client scenarios:
@@ -77,6 +88,17 @@ This will make the MCP server available at 'http://localhost:3000/mcp'.
 
 ### Environment variables
 
+Currently you only need the Figma personal access token if you want to enable the [Figma to code generation tool](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens). You set this variable in your MCP client configuration file.
+
+```bash
+// other options
+"env": {
+  "FIGMA_ACCESS_TOKEN": "YOUR_PERSONAL_FIGMA_ACCESS_TOKEN"
+}
+```
+
+### Hosting variables
+
 Configure the server behavior with these environment variables:
 
 ```bash
@@ -93,48 +115,23 @@ MCP_HOST=0.0.0.0
 MCP_CORS_ORIGINS=http://localhost:3000,https://myapp.com
 ```
 
-## Installation & Setup
-
-Make sure that you have the following installed:
+## Integration examples
 
-- Node.js 16+ installed
-- Tailwind CSS v4+ (for generated themes)
-
-### Local development
-
-```bash
-# Clone the repository
-git clone https://github.com/themesberg/flowbite-mcp.git
-cd flowbite-mcp
-
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Run in stdio mode (for Claude Desktop, Cursor)
-npm start
-
-# Run inspector
-npm run start inspector
-
-# Run in HTTP server mode (for production/multi-client)
-MCP_TRANSPORT_MODE=http npm start
-```
-
-## Integration Examples
+Use the following configuration examples to install the Flowbite MCP server in popular clients such as Cursor, Claude, Windsurf, and more.
 
 ### Claude desktop
 
-**Method 1: Using NPX**
+Update the `claude_desktop_config.json` file and add the following configuration:
 
 ```json
 {
   "mcpServers": {
     "flowbite": {
       "command": "npx",
-      "args": ["-y", "flowbite-mcp"]
+      "args": ["-y", "flowbite-mcp"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "YOUR_PERSONAL_FIGMA_ACCESS_TOKEN"
+      }
     }
   }
 }
@@ -142,52 +139,69 @@ MCP_TRANSPORT_MODE=http npm start
 
 ### Cursor editor
 
-**With NPX:**
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=flowbite&config=eyJlbnYiOnsiRklHTUFfQUNDRVNTX1RPS0VOIjoiWU9VUl9QRVJTT05BTF9GSUdNQV9BQ0NFU1NfVE9LRU4ifSwiY29tbWFuZCI6Im5weCAteSBmbG93Yml0ZS1tY3AifQ%3D%3D)
+
+Update the `mcp.json` file and add the following configuration:
 
 ```json
 {
   "mcpServers": {
     "flowbite": {
       "command": "npx",
-      "args": ["-y", "flowbite-mcp"]
+      "args": ["-y", "flowbite-mcp"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "YOUR_PERSONAL_FIGMA_ACCESS_TOKEN"
+      }
     }
   }
 }
 ```
 
-### Continue.dev
+### Windsurf editor
+
+Update the `mcp_config.json` file and add the following configuration:
 
 ```json
 {
-  "mcpServers": [
-    {
-      "name": "flowbite",
+  "mcpServers": {
+    "flowbite": {
       "command": "npx",
-      "args": ["-y", "flowbite-mcp"]
+      "args": ["-y", "flowbite-mcp"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "YOUR_PERSONAL_FIGMA_ACCESS_TOKEN"
+      }
     }
-  ]
+  }
 }
 ```
 
-### Local Development
+### Glama.ai
+
+<a href="https://glama.ai/mcp/servers/@zoltanszogyenyi/flowbite-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@zoltanszogyenyi/flowbite-mcp/badge" />
+</a>
 
-For development or running from source:
+### Local development
 
 ```bash
+# Clone the repository
+git clone https://github.com/themesberg/flowbite-mcp.git
+cd flowbite-mcp
+
 # Install dependencies
 npm install
 
 # Build the project
 npm run build
 
-# Run in stdio mode
+# Run in stdio mode (for Claude Desktop, Cursor)
 npm start
 
-# Run in HTTP server mode
-npm run start:http
+# Run inspector
+npm run start inspector
 
-# Development mode with auto-reload
-npm run dev
+# Run in HTTP server mode (for production/multi-client)
+MCP_TRANSPORT_MODE=http npm start
 ```
 
 ### Production deployment (HTTP Mode)
@@ -318,7 +332,7 @@ This project is licensed under the MIT License License - see the [LICENSE](LICEN
 - [x] AI-powered theme generator
 - [x] Dual transport support (stdio + HTTP)
 - [ ] Flowbite Pro blocks integration (with license authentication)
-- [ ] Figma to code conversion tool
+- [x] Figma to code conversion tool
 - [ ] Enhanced theme customization options
 - [ ] Component search and filtering
 - [ ] Real-time component preview generation

package/build/index.js

@@ -551,6 +551,22 @@ const getDataPath = (relativePath) => {
 };
 // Function to setup all resources and tools
 const setupServer = (server) => {
+    server.resource("flowbite_overview", "flowbite://overview/file", {
+        description: "Overview of the Flowbite MCP server and its capabilities.",
+        title: "Flowbite Overview",
+        mimeType: "text/markdown",
+    }, async (uri) => {
+        const overviewContent = readFileSync(getDataPath("overview.md"), "utf-8");
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    text: overviewContent,
+                    mimeType: "text/markdown",
+                },
+            ],
+        };
+    });
     server.resource("flowbite_theme", "flowbite://theme/file", {
         description: "The theme file that sets the Tailwind CSS variables to make UI look unique for every website.",
         title: "Flowbite Theme",
@@ -615,41 +631,250 @@ const setupServer = (server) => {
             };
         });
     });
-    server.tool('convert-figma-to-code', 'Converts a Figma layer to a code block', {
-        figmaNodeUrl: z.string().describe('The URL of the Figma node to convert'),
+    server.tool('convert-figma-to-code', 'Fetches a Figma node and its rendered image from the Figma API and converts it to a code block. Requires FIGMA_ACCESS_TOKEN environment variable to be set.', {
+        figmaNodeUrl: z.string().describe('The URL of the Figma node (e.g., https://www.figma.com/design/fileKey/fileName?node-id=123-456)'),
     }, async ({ figmaNodeUrl }) => {
         try {
+            // Get Figma access token from environment variables
+            const figmaAccessToken = process.env.FIGMA_ACCESS_TOKEN;
+            if (!figmaAccessToken) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: FIGMA_ACCESS_TOKEN environment variable is not set.
+
+To use this tool, you need to:
+1. Generate a Personal Access Token from Figma:
+   - Go to Figma > Settings > Account > Personal access tokens
+   - Generate a new token
+2. Set the FIGMA_ACCESS_TOKEN environment variable with your token
+
+Example for your MCP config:
+{
+  "env": {
+    "FIGMA_ACCESS_TOKEN": "your-personal-access-token"
+  }
+}`,
+                        },
+                    ],
+                };
+            }
+            // Parse Figma URL to extract fileKey and nodeId
+            // URL formats:
+            // https://www.figma.com/file/{fileKey}/{fileName}?node-id={nodeId}
+            // https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+            const urlPattern = /figma\.com\/(file|design)\/([a-zA-Z0-9]+)(?:\/[^?]*)?(?:\?.*node-id=([^&]+))?/;
+            const match = figmaNodeUrl.match(urlPattern);
+            if (!match) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: Invalid Figma URL format.
+
+Expected formats:
+- https://www.figma.com/file/{fileKey}/{fileName}?node-id={nodeId}
+- https://www.figma.com/design/{fileKey}/{fileName}?node-id={nodeId}
+
+Provided URL: ${figmaNodeUrl}`,
+                        },
+                    ],
+                };
+            }
+            const fileKey = match[2];
+            const nodeId = match[3] ? decodeURIComponent(match[3]) : null;
+            if (!nodeId) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error: No node-id found in the Figma URL.
+
+Please make sure your URL includes a node-id parameter.
+Example: https://www.figma.com/design/${fileKey}/FileName?node-id=123-456
+
+Provided URL: ${figmaNodeUrl}`,
+                        },
+                    ],
+                };
+            }
+            // API headers
+            const headers = {
+                'X-Figma-Token': figmaAccessToken,
+            };
+            // Fetch node data
+            const nodeApiUrl = `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${encodeURIComponent(nodeId)}`;
+            const nodeResponse = await fetch(nodeApiUrl, { headers });
+            if (!nodeResponse.ok) {
+                const errorText = await nodeResponse.text();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching Figma node data:
+Status: ${nodeResponse.status} ${nodeResponse.statusText}
+Response: ${errorText}
+
+API URL: ${nodeApiUrl}`,
+                        },
+                    ],
+                };
+            }
+            const nodeData = await nodeResponse.json();
+            // Fetch node image
+            const imageApiUrl = `https://api.figma.com/v1/images/${fileKey}?ids=${encodeURIComponent(nodeId)}&scale=2`;
+            const imageResponse = await fetch(imageApiUrl, { headers });
+            if (!imageResponse.ok) {
+                const errorText = await imageResponse.text();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error fetching Figma node image:
+Status: ${imageResponse.status} ${imageResponse.statusText}
+Response: ${errorText}
+
+API URL: ${imageApiUrl}
+Node data was retrieved successfully.`,
+                        },
+                    ],
+                };
+            }
+            const imageData = await imageResponse.json();
+            // Extract the image URL from the response
+            const imageUrl = imageData.images?.[nodeId] || imageData.images?.[Object.keys(imageData.images)[0]] || null;
+            // Return combined result with AI instructions
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Code block converted`,
+                        text: `# Figma to Code Conversion Task
+
+## Instructions for AI
+
+You have received a Figma design that needs to be converted to code. Follow these steps:
+
+### Step 1: Analyze the Design
+Look at the rendered image below and the node structure data to understand:
+- The layout and component hierarchy
+- Colors, typography, and spacing used
+- Interactive elements (buttons, inputs, links, etc.)
+- Component patterns that match Flowbite components
+
+### Step 2: Use Flowbite MCP Resources
+Before writing code, fetch the relevant Flowbite component documentation using the MCP resources. Based on the design, you may need:
+
+**Common Components to Check:**
+- \`flowbite://components/buttons\` - For button styles
+- \`flowbite://components/card\` - For card layouts
+- \`flowbite://components/navbar\` - For navigation bars
+- \`flowbite://components/modal\` - For modal dialogs
+- \`flowbite://components/forms\` - For form layouts
+- \`flowbite://forms/input-field\` - For input fields
+- \`flowbite://components/avatar\` - For user avatars
+- \`flowbite://components/badge\` - For badges/tags
+- \`flowbite://components/tables\` - For data tables
+- \`flowbite://components/tabs\` - For tab navigation
+- \`flowbite://components/dropdowns\` - For dropdown menus
+- \`flowbite://components/sidebar\` - For sidebar navigation
+- \`flowbite://components/footer\` - For footer sections
+- \`flowbite://typography/headings\` - For heading styles
+- \`flowbite://typography/text\` - For text styles
+
+### Step 3: Write the Code
+Generate clean, semantic HTML with Tailwind CSS classes following these guidelines:
+
+1. **Use Flowbite Components**: Match the Figma design to Flowbite components whenever possible
+2. **Tailwind CSS Classes**: Use Tailwind utility classes for styling
+3. **Responsive Design**: Include responsive breakpoints (sm:, md:, lg:, xl:)
+4. **Semantic HTML**: Use proper HTML5 semantic elements
+5. **Accessibility**: Include ARIA attributes and proper alt texts
+6. **Match Colors**: Use Flowbite variables and secondly Tailwind color classes that best match the Figma design colors
+7. **Match Spacing**: Use Tailwind spacing utilities (p-*, m-*, gap-*) to match the design
+
+### Step 4: Output Format - IMPORTANT
+
+**⚠️ ONLY output the component code block - DO NOT include:**
+- \`<!DOCTYPE html>\`
+- \`<html>\`, \`</html>\` tags
+- \`<head>\`, \`</head>\` tags
+- \`<body>\`, \`</body>\` tags
+- \`<link>\` tags (CSS imports)
+- \`<script>\` tags (JS imports)
+- Any meta tags or document structure
+- ':dark' variant classes unless explicitly requested
+
+**✅ DO output:**
+- Only the component HTML markup itself
+- The actual UI component code that would go inside a \`<body>\` tag
+- Clean, well-formatted code block with proper indentation
+- Just the reusable component/section code
+- When possible use the "brand" variables from Flowbite instead of hardcoded colors from Tailwind CSS
+
+**Example of what to output:**
+\`\`\`html
+<div class="bg-neutral-primary-soft block max-w-sm p-6 border border-default rounded-base shadow-xs">
+    <h5 class="mb-3 text-2xl font-semibold tracking-tight text-heading leading-8">Noteworthy technology acquisitions 2021</h5>
+    <p class="text-body mb-6">Here are the biggest technology acquisitions of 2025 so far, in reverse chronological order.</p>
+    <a href="#" class="inline-flex items-center text-white bg-brand box-border border border-transparent hover:bg-brand-strong focus:ring-4 focus:ring-brand-medium shadow-xs font-medium leading-5 rounded-base text-sm px-4 py-2.5 focus:outline-none">
+        Read more
+        <svg class="w-4 h-4 ms-1.5 rtl:rotate-180 -me-0.5" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" viewBox="0 0 24 24"><path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 12H5m14 0-4 4m4-4-4-4"/></svg>
+    </a>
+</div>
+\`\`\`
+
+---
+
+## Figma Design Data
+
+### File Information
+- **File Key**: ${fileKey}
+- **Node ID**: ${nodeId}
+- **Source URL**: ${figmaNodeUrl}
+
+### Rendered Design Image
+${imageUrl ? `![Figma Design](${imageUrl})
+
+**Direct Image URL**: ${imageUrl}` : '⚠️ No image URL available - analyze the node data structure below'}
+
+### Node Structure Data
+The following JSON contains the Figma node structure with layers, styles, and properties:
+
+\`\`\`json
+${JSON.stringify(nodeData, null, 2)}
+\`\`\`
+
+---
+
+## Now Convert This Design
+
+Based on the image and node data above:
+1. Identify the UI components visible in the design
+2. Fetch the relevant Flowbite component documentation from the MCP resources
+3. Generate ONLY the component HTML/Tailwind CSS code (no document wrapper, no \`<html>\`, \`<head>\`, \`<body>\`, \`<link>\`, or \`<script>\` tags)
+4. Ensure the code is production-ready with proper responsiveness and accessibility`,
                     },
                 ],
             };
         }
         catch (error) {
-            console.error(`Error converting Figma node to code: ${error}`);
+            console.error(`Error fetching Figma node: ${error}`);
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Error converting Figma node to code: ${error}`,
+                        text: `Error fetching Figma node: ${error instanceof Error ? error.message : String(error)}
+
+Please check:
+1. Your FIGMA_ACCESS_TOKEN is valid
+2. The Figma URL is correct
+3. You have access to the Figma file`,
                     },
                 ],
             };
         }
     });
-    server.tool('get_session', 'gets the session id and context', {}, async ({}) => {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `session`,
-                },
-            ],
-        };
-    });
     server.tool('generate-theme', 'Generates a custom Flowbite theme CSS file based on a brand color (hex format) and user instructions. The AI will intelligently analyze the instructions and customize ALL theme variables (border radius, spacing, colors, typography, etc.) to match the desired aesthetic. This tool creates color shades and variations, adapting the entire theme system to match your brand identity.', {
         brandColor: z.string().describe('The primary brand color in hex format (e.g., #3B82F6, #FF5733). This will be used as the base for generating all brand color variations.'),
         instructions: z.string().describe('Natural language instructions describing the desired theme aesthetic and customizations. The AI will interpret these instructions to modify all relevant theme variables. Examples: "Make it modern and minimalist with soft rounded corners", "Create a luxury feel with gold accents and elegant spacing", "Design for a playful children\'s app with bright colors", "Professional corporate style with subtle borders", etc.'),

package/data/overview.md

@@ -0,0 +1,12 @@
+# Flowbite MCP Server Overview
+
+This MCP server provides access to Flowbite's extensive library of Tailwind CSS components and theme generation capabilities.
+
+## Features
+
+- resources that have access to the full Flowbite component library including the open source components, plugins, and typography
+- tools to allow the generation of UI components, layouts and the theme file that allow customization
+
+## Supporting Flowbite
+
+To support the open-source development of Flowbite please consider purchasing the [Pro version of Flowbite](https://flowbite.com/pro/#pricing) to get access to hundreds of premium building blocks, a Figma design system, and other templates like dashboard layouts and marketing websites.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flowbite-mcp",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Model Context Protocol server providing AI assistants with access to Flowbite UI components and an intelligent theme generator for Tailwind CSS",
   "main": "build/index.js",
   "type": "module",
@@ -11,8 +11,7 @@
     "build",
     "data",
     "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
+    "LICENSE"
   ],
   "publishConfig": {
     "access": "public"