Storybook MCP

🚀 Storybook MCP Server

A Model Context Protocol (MCP) server offering tools to interact with Storybook documentation and component information.

✨ Features

• getComponentList: Retrieve a list of all components from a configured Storybook.
• getComponentsProps: Obtain detailed props information for multiple components via headless browser automation.
• Custom Tools: Develop custom tools to extract any information from your Storybook pages using JavaScript.

📦 Installation and Configuration

MCP Settings

Include the following configuration in MCP settings:

{
  "mcpServers": {
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp"],
      "env": {
        "STORYBOOK_URL": "<your_storybook_url>/index.json"
      }
    }
  }
}

Environment Variables

• STORYBOOK_URL (required): The URL to your Storybook's index.json file.
• CUSTOM_TOOLS (optional): JSON array of custom tool definitions for extracting specific information from your Storybook.

💻 Usage

The server offers built - in tools and supports custom tools:

Built-in Tools

1. getComponentList

Fetches a list of all available components from the configured Storybook. Example:

Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

Retrieves detailed props information for multiple components, including:

• Property names
• Types
• Default values
• Descriptions
• Required/optional status

Parameters:

• componentNames (array of strings): Array of component names to get props information for.

Example usage:

Tool: getComponentsProps
Parameters: { "componentNames": ["Button", "Input", "Avatar"] }

Custom Tools

You can define custom tools to extract specific information from your Storybook pages. Each custom tool can:

• Navigate to any page in your Storybook.
• Execute custom JavaScript to extract data.
• Return structured data to the AI assistant.

Custom Tool Structure:

interface CustomTool {
  name: string;           // Unique tool name
  description: string;    // Tool description for the AI
  parameters: object;     // Input parameters schema (optional)
  page: string;          // URL to navigate to
  handler: string;       // JavaScript code to execute on the page
}

Example Custom Tools:

[
  {
    "name": "getIconList",
    "description": "Get All Icons from the Icon page",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "Extract color palette from design tokens",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/design-tokens--colors",
    "handler": "Array.from(document.querySelectorAll('.color-swatch')).map(el => ({ name: el.getAttribute('data-color-name'), value: el.style.backgroundColor }))"
  }
]

For more examples and detailed documentation, see examples/custom-tools-example.md.

🔧 Technical Details

How it works

1. Component List: The server fetches the Storybook's index.json file (v3 is stories.json) and extracts all components marked as "docs" type.
2. Props Information: For component props, the server:
   • Finds the component's documentation ID from the index.json.
   • Constructs the iframe URL for the component's docs page.
   • Uses Playwright to load the page in a headless browser.
   • Extracts the props table HTML from the documentation.

Supported Storybook URLs

The server is compatible with any Storybook that exposes an index.json file (v3 is stories.json). Common patterns:

• https://your-storybook-domain.com/index.json
• https://your-storybook-domain.com/storybook/index.json

🛠️ Development

Local Development

1. Clone the repository.
2. Install dependencies: yarn install.
3. Install Playwright browsers: npx playwright install chromium.
4. Set the environment variable: export STORYBOOK_URL="your-storybook-url".
5. Run in development mode: yarn dev.

⚠️ Important Note

You can also use npx @modelcontextprotocol/inspector tsx src/index.ts instead of yarn dev if you prefer.

Building

yarn build

Testing

yarn test

Requirements

• Node.js 18.0.0 or higher.
• Chromium browser (automatically installed with Playwright).

Error Handling

The server features comprehensive error handling for:

• Missing or invalid Storybook URLs.
• Network connectivity issues.
• Component not found scenarios.
• Playwright browser automation failures.

📄 License

Storybook MCP is MIT licensed.