freema/mcp-design-system-extractor

A Model Context Protocol (MCP) server that extracts component information from Storybook design systems. Connects to Storybook instances and extracts HTML, styles, and component metadata.
Installation
Using Claude CLI (Recommended)
With self-signed certificate:
Using npm
Then configure in your MCP client (see Environment Variables).
From Source
Key Dependencies
- **Puppeteer**: Uses headless Chrome for dynamic JavaScript component rendering
- **Chrome/Chromium**: Required for Puppeteer (automatically handled in Docker)
- Works with built Storybook distributions
Features
- **List Components**: Get all available components from your Storybook with compact mode
- **Extract HTML**: Get the rendered HTML of any component (async or sync mode)
- **Search Components**: Find components by name, title, category, or purpose
- **Component Dependencies**: Analyze which components are used within other components
- **Theme Information**: Extract design system theme (colors, spacing, typography)
- **External CSS Analysis**: Fetch and analyze CSS files to extract design tokens
- **Async Job Queue**: Long-running operations run in background with job tracking
Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| STORYBOOK_URL | URL of your Storybook instance | http://localhost:6006 |
| NODE_TLS_REJECT_UNAUTHORIZED | Set to 0 to skip SSL certificate verification (for self-signed certs) | 1 |
**Example with self-signed certificate:**
Usage
See DEVELOPMENT.md for detailed setup instructions.
Available Tools (9 total)
Core Tools
1. **list_components**
- Lists all available components from the Storybook instance
- Use compact: true for minimal output (reduces response size)
- Filter by category parameter
- Supports pagination with page and pageSize (default: 20)
2. **get_component_html**
- Extracts HTML from a specific component story
- **Async by default**: Returns job_id, use job_status to poll for results
- Set async: false for synchronous mode (uses timeout parameter)
- Use variantsOnly: true to get list of available variants (sync, fast)
- Optional includeStyles: true for CSS extraction (Storybook CSS filtered out)
- Story ID format: "component-name--story-name" or just "component-name" (auto-resolves to default variant)
3. **search_components**
- Search components by name, title, category, or purpose
- query: Search term (use "*" for all)
- purpose: Find by function ("form inputs", "navigation", "feedback", "buttons", etc.)
- searchIn: "name", "title", "category", or "all" (default)
- Supports pagination with page and pageSize
Component Analysis Tools
4. **get_component_dependencies**
- Analyzes rendered HTML to find which other components are used internally
- Detects React components, web components, and CSS class patterns
- Requires story ID format: "component-name--story-name"
Design System Tools
5. **get_theme_info**
- Extracts design system theme (colors, spacing, typography, breakpoints)
- Gets CSS custom properties/variables
- Use includeAll: true for all CSS variables
6. **get_external_css**
- **DEFAULT**: Returns only design tokens + file stats (avoids token limits)
- Extracts & categorizes tokens: colors, spacing, typography, shadows