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)

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=http://localhost:6006

With self-signed certificate:

claude mcp add design-system npx mcp-design-system-extractor@latest \
  --env STORYBOOK_URL=https://my-storybook.example.com \
  --env NODE_TLS_REJECT_UNAUTHORIZED=0

Using npm

npm install -g mcp-design-system-extractor

Then configure in your MCP client (see Environment Variables).

From Source

git clone https://github.com/freema/mcp-design-system-extractor.git
cd mcp-design-system-extractor
npm install && npm run build
npm run setup  # Interactive setup for Claude Desktop

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

Example with self-signed certificate:

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "STORYBOOK_URL": "https://my-storybook.example.com",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

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 fi

... View full README on GitHub