Livewire Flux MCP

An MCP (Model Context Protocol) server that provides access to Livewire Flux Components and Layouts from Livewire Flux. This server allows AI assistants to fetch and search through Flux component and layout documentation on demand.

⚠️ Disclaimer

This is a personal project and is not affiliated with Livewire Flux.

What it does

This MCP server scrapes and provides structured access to the Livewire Flux documentation, enabling AI assistants to:

• Fetch documentation for specific Flux components from https://fluxui.dev/components/
• Fetch documentation for specific Flux layouts from https://fluxui.dev/layouts/
• Access component and layout reference sections with API details, props, and usage patterns
• Search through component and layout documentation content
• List all available Flux components
• Browse and search all available Heroicons for use with flux:icon component
• Access up-to-date documentation directly from the official Flux website
• High-performance caching with 24-hour expiration for optimal response times

Why not just Laravel Boost?

Boost already indexes Flux through its search-docs tool, and for a lot of questions that is enough. Two things it does not do:

• Scoped answers. search-docs is a semantic search over a 17k-document corpus, so a broad Flux question can come back as a several-thousand-token dump (laravel/boost#290). This server fetches the one component page you asked for, plus its reference section.
• Pro-tier awareness. Boost's bundled fluxui-development skill carries a hardcoded component list and does not tell your agent which components need a paid Flux license. This server reads the tier live and flags it, so your agent stops writing markup you cannot ship.

If you are on Boost, npx livewire-flux-mcp install wires both together — see AI Guidelines & Skills. The two are complementary: keep Boost for Laravel, Livewire, Pest and the rest; let this server answer Flux.

Set Up Your Agents

The server runs over stdio and is launched with npx, so there is nothing to install globally. Every agent stores that differently — pick yours below.

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

claude mcp add --transport stdio --scope project flux-docs -- npx -y livewire-flux-mcp

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

codex mcp add flux-docs -- npx -y livewire-flux-mcp

[mcp_servers.flux-docs]
command = "npx"
args = ["-y", "livewire-flux-mcp"]

gemini mcp add --scope project flux-docs npx -y livewire-flux-mcp

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

{
    "servers": {
        "flux-docs": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

code --add-mcp '{"name":"flux-docs","command":"npx","args":["-y","livewire-flux-mcp"]}'

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

AI Guidelines & Skills

Registering the server tells your agent the tools exist. It does not tell it when to reach for them — and in a Laravel Boost project it actively will not, because Boost ships a fluxui-development skill that sends Flux lookups to its own search-docs tool and carries a hardcoded component list. This package ships guidance that fixes that:

npx livewire-flux-mcp install

The installer detects what applies: livewire/flux-pro in composer.json selects the fluxui-pro guideline key, livewire/flux selects fluxui-free, and a .claude/ directory adds the subagent. Restrict it with --boost or --claude, point it elsewhere with --path <dir>, or preview with --dry-run. Afterwards run php artisan boost:update so Boost picks the files up.

On overwriting. The skill is a deliberate replacement — Boost resolves custom skills last and keys them on the frontmatter name, so fluxui-development has to match for the override to land. The guideline is never clobbered: an existing file at that path, or the guideline shipped inside the Flux package itself, is preserved below our block, which is delimited by {{-- livewire-flux-mcp:begin --}} markers so re-running only refreshes that section. Any file the installer did not write is left alone unless you pass --force.

To undo, delete the installed files and run php artisan boost:update — Boost restores its own versions.

Laravel Boost only auto-discovers guidelines and skills from Composer packages, so an npm package cannot register them automatically. This installer writes to the paths Boost documents for custom guidelines and skills, which is why it works and survives boost:update.

Support Me

Hey folks,

Do you like this package? Do you find it useful, and it fits well in your project?

I am glad to help you, and I would be so grateful if you considered supporting my work.

You can even choose 😃:

• You can sponsor me 😎
• You can buy me a coffee ☕ or a pizza 🍕
• You can "Star ⭐" this repository (it's free BTW 😉)

Available MCP Tools

The server provides four MCP tools:

1. fetch_flux_docs - Fetches documentation for components or layouts

   • component (optional): Specific component name to fetch docs for
   • layout (optional): Specific layout name to fetch docs for (e.g., "header", "sidebar")
   • version (optional): Flux major version to target — 'v1' or 'v2' (default 'v2')
   • Automatically includes reference sections when available
   • Fetches from https://fluxui.dev/components/{component} or https://fluxui.dev/layouts/{layout} (v2); routes to https://v1.fluxui.dev/components/{component} when version='v1'
   • When the page is a paid Flux component, a [NOTICE] This is a Flux Pro component … line is prepended to the response

2. list_flux_components - Lists all available Flux components

   • version (optional): 'v1' or 'v2' (default 'v2')
   • tier (optional): 'free', 'pro', or 'all' (default 'all'). On 'all', each component is annotated [Pro] or [Free]. On v1, the tier argument is ignored (v1 has no Pro tier).
   • Provides component names and their documentation paths

3. list_flux_layouts - Lists all available Flux layouts

   • version (optional): 'v1' or 'v2' (default 'v2'). On v1 the tool returns a brief "layouts are not available in v1" notice without making any HTTP request.
   • Provides layout names and their documentation paths
   • Layout names are read from fluxui.dev/layouts, falling back to the site-wide navigation on fluxui.dev/components when that index is unavailable — the individual /layouts/{name} pages are unaffected either way

4. list_flux_component_icons - Lists all available Heroicons for flux:icon component

   • variant (optional): Filter by icon variant (outline, solid, mini, micro)
   • search (optional): Search term to filter icon names
   • Fetches actual icon names from Heroicons GitHub repository
   • Provides usage examples, dimensions, and GitHub links for each variant
   • Returns comprehensive list of all available icons with proper Flux syntax

Example Usage

Once the MCP server is running, AI assistants can use it to:

• Get documentation for a specific component: "Show me the Button component docs"
• Get documentation for a specific layout: "Show me the header layout docs"
• List available components: "What Flux components are available?"
• List available layouts: "What Flux layouts are available?"
• Browse all available icons: "Show me all Heroicons available for flux:icon"
• Search for specific icons: "Find all arrow icons in the outline variant"
• Get icon usage examples: "How do I use the user icon in solid variant?"

The server automatically fetches the latest documentation from fluxui.dev/components, fluxui.dev/layouts, and Heroicons from GitHub, presenting everything in a structured format for easy consumption by AI assistants. When fetching component or layout documentation, it includes both the main content and the reference section with detailed API information.

Versions

Flux ships in two major versions, and the MCP server supports both:

• v2 (default) — the current host at fluxui.dev. Used when version is omitted or set to 'v2'. Supports components, layouts, and Pro-tier awareness.
• v1 — the legacy host at v1.fluxui.dev. Used when version='v1'. Components only — Flux v1 has no /layouts route and no Pro tier. list_flux_layouts returns a friendly notice on v1 without making any HTTP request; tier is ignored on list_flux_components for v1.

The version argument is accepted on fetch_flux_docs, list_flux_components, and list_flux_layouts. list_flux_component_icons is version-independent (Heroicons are not part of Flux versioning).

Pro tier awareness

A subset of Flux v2 components is only available with a paid Flux Pro license. The MCP server surfaces this in two ways:

• Notice on fetch. When fetch_flux_docs retrieves a component that is Pro, the response is prepended with a single [NOTICE] This is a Flux Pro component — requires a paid Flux license. line.
• Tier filter on listing. list_flux_components accepts tier='free' to hide Pro components, tier='pro' to show only Pro ones, or tier='all' (default) to list everything with [Pro] / [Free] annotations next to each name.

The list of Pro components is derived from fluxui.dev/pricing with a hardcoded fallback baked into the server, so tier filtering still works correctly if the pricing page is unreachable.

Manually Registering the MCP Server

If your editor is not one of the six covered in Set Up Your Agents, register the server manually using the following details:

{
    "mcpServers": {
        "flux-docs": {
            "command": "npx",
            "args": ["-y", "livewire-flux-mcp"]
        }
    }
}

-y skips the install confirmation on first launch, which a stdio server cannot answer.

Performance & Caching

The MCP server includes intelligent caching to provide optimal performance:

• 24-hour cache expiration - Content is cached for 1 day to balance freshness with performance
• Automatic cache management - Expired entries are automatically cleaned up
• Intelligent cache keys - Different cache entries for different parameters (component, layout, version, tier, variant)
• GitHub API rate limit protection - Prevents hitting GitHub API limits when fetching Heroicons
• Instant responses - Cached requests return in milliseconds instead of seconds

Cache Behavior

• Documentation requests: Cached per component/layout and version combination
• Component listings: Cached globally (refreshed daily)
• Layout listings: Cached globally (refreshed daily)
• Icon listings: Cached per variant and search combination
• Cache storage: In-memory (resets when server restarts)

The caching system is particularly beneficial for the list_flux_component_icons tool, which can make up to 4 GitHub API calls per request without caching.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Maurizio
• All Contributors

License

The MIT License (MIT). Please see License File for more information.