MCP Design System Extractor

What freema/mcp-design-system-extractor MCP server does

The freema/mcp-design-system-extractor MCP server exposes a Storybook design system through MCP tools. It can list components, search by name, title, category, or purpose, and retrieve rendered HTML for a selected story. HTML results can include CSS extracted from the rendered component, with Storybook's own CSS filtered out.

The server also exposes design-system analysis capabilities. It can inspect component dependencies in rendered HTML, extract theme information such as colors, spacing, typography, and breakpoints, and read CSS custom properties. External CSS analysis categorizes tokens including colors, spacing, typography, and shadows. By default, external CSS results contain design tokens and file statistics rather than the full stylesheet.

How it works

The server reads the Storybook story index from /index.json, with /stories.json as a fallback, and renders stories through /iframe.html. Puppeteer drives headless Chrome so JavaScript-rendered components can be inspected rather than treated as static files.

HTML extraction is asynchronous by default. The request returns a job identifier, and the job_status tool can be used to retrieve the result after completion. Synchronous extraction is available when a timeout is supplied. The queue supports up to two concurrent jobs and retains completed jobs for one hour. Job listing and cancellation are available through separate MCP tools.

Storybook versions 7 through 10 are supported. Storybook 6 and earlier are not supported because they use different endpoints.

Setup and configuration

Install the package globally with npm or run mcp-design-system-extractor@latest through npx. The server requires Node.js 20 or newer, a running Storybook instance, and Chrome or Chromium for Puppeteer. Docker handles Chrome or Chromium automatically when used in that environment.

Set STORYBOOK_URL to the Storybook address. It defaults to http://localhost:6006, so it can be omitted when the local default is appropriate. For a Storybook using a self-signed certificate, set NODE_TLS_REJECT_UNAUTHORIZED=0; this disables certificate verification and should be used only when that behavior is acceptable.

The repository documents setup through the Claude CLI, npm installation, and a source build followed by npm run setup for an interactive Claude Desktop configuration.

Tools and capabilities

The MCP tool set includes:

• list_components for paginated component discovery, with compact output and category filtering.
• search_components for searches across names, titles, categories, or purposes; "*" can request all matches.
• get_component_html for story markup, variants, optional styles, synchronous extraction, or asynchronous jobs.
• get_component_dependencies for identifying React components, web components, and CSS class patterns in rendered HTML.
• get_theme_info for theme values and CSS variables, including an option to return all variables.
• get_external_css for same-domain stylesheet analysis and token extraction.
• job_status, job_cancel, and job_list for asynchronous job management.

Limitations and notes

The freema/mcp-design-system-extractor MCP server depends on a reachable Storybook deployment and compatible Storybook endpoints. External CSS requests are restricted to URLs on the same domain as the configured Storybook. Full CSS output can be large, so token-only output is the default. Large component renders are better suited to asynchronous mode, while variantsOnly provides a faster way to discover available variants.