Purpose
mcp-design-system-extractor is a Model Context Protocol (MCP) server that enables AI assistants to interact with the Storybook design system, extracting component information from a Storybook instance to help with design system adoption and refactoring.
It connects to a Storybook instance and extracts HTML, styles, and component metadata. It uses Puppeteer headless Chrome for dynamic JavaScript component rendering and can be used with built Storybook distributions.
Main Capabilities
The server provides a total of 9 tools:
Component Discovery
- list_components: Lists all available components in the Storybook instance. Use compact: true to streamline output (reduce response size); can filter by the category parameter; supports pagination using page and pageSize (default 20).
- search_components: Searches for components by name, title, category, or purpose. query is the search term (use "*" to mean all); purpose can find by function ("form inputs", "navigation", "feedback", "buttons", etc.); searchIn can be "name", "title", "category", or "all" (default); supports pagination.
Component Extraction
- get_component_html: Extracts HTML from the specified component story. Asynchronous by default: returns a job_id, poll for the result with job_status; can set async: false to switch to synchronous mode (using the timeout parameter); use variantsOnly: true to get the list of available variants (synchronous, fast); optionally includeStyles: true to extract CSS (Storybook's own CSS is filtered out). Story ID format is "component-name--story-name", or just "component-name" (automatically resolves to the default variant).
Component Analysis
- get_component_dependencies: Analyzes the rendered HTML to find which other components are used internally. Can detect React components, Web Components, and CSS class patterns. Requires story ID format "component-name--story-name".
Design System
- get_theme_info: Extracts the design system theme (colors, spacing, fonts, breakpoints), retrieving CSS custom properties/variables. Use includeAll: true to get all CSS variables.
- get_external_css: By default returns only design tokens + file statistics (to avoid token limits); extracts and categorizes tokens: colors, spacing, fonts, shadows; use includeFullCSS: true only when the full CSS content is needed; protected by security, only accepting URLs on the same domain as Storybook.
Task Management
- job_status: Checks asynchronous task status, returning status, result (when complete), error (when failed). Poll after calling get_component_html in asynchronous mode.
- job_cancel: Cancels a queued or running task, returning whether the cancellation succeeded.
- job_list: Lists all tasks and their statuses. Can filter by status: "all" (default), "active" (queued/running), "completed". Returns the task list + queue statistics.
Usage
Can be used via the Claude CLI (recommended), supporting self-signed certificates. Then configure it in the MCP client (see environment variables).
Key dependencies:
- Puppeteer: uses headless Chrome for dynamic JavaScript component rendering
- Chrome/Chromium: required by Puppeteer (automatically handled in Docker)
Connection mechanism: connects to Storybook via the /index.json and /iframe.html endpoints; uses Puppeteer headless Chrome for dynamic JavaScript rendering; uses an in-memory task queue for long-running operations, with a maximum of 2 concurrent tasks and a 1-hour TTL for completed tasks.
Environment variables include STORYBOOK_URL, etc. For self-signed certificate scenarios, you can set NODE_TLS_REJECT_UNAUTHORIZED=0.
Use Cases
- Component discovery
- Building new features
- Design system analysis
- Component migration
- Multi-tool workflows
Limitations and Requirements
- Requires Chrome/Chromium (for Puppeteer)
- Requires a running Storybook instance
- Supported Storybook versions: Storybook 7, 8, 9, 10. The server reads the story index from /index.json, falls back to /stories.json, and renders stories via /iframe.html?id=<storyId>—these endpoints remain stable across the four major versions.
- Storybook 6 and earlier are not supported: they predate /index.json and use a different story-id scheme.
- Both a development server (npm run storybook) and a built static Storybook served over HTTP work.
Usage Recommendations
- Start with discovery: use list_components with compact: true
- Get variants first: use get_component_html with variantsOnly: true
- Use async for HTML: the default async mode avoids timeouts on large components
- Poll job_status: check task completion before reading results
- Search by purpose: use the purpose parameter of search_components
Troubleshooting
- Make sure Storybook is running and STORYBOOK_URL is correct
- First use list_components to see available components
- For large components, use async mode (the default) and poll job_status
- Inspect the /index.json endpoint directly in the browser
- SSL certificate errors: set NODE_TLS_REJECT_UNAUTHORIZED=0 for self-signed certificates
For more detailed development and setup instructions, see DEVELOPMENT.md.
