Storybook MCP Server

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

Features

• getComponentList: Get a list of all components from a configured Storybook
• getComponentsProps: Get detailed props information for multiple components using headless browser automation
• Custom Tools: Create custom tools that can extract any information from your Storybook pages using JavaScript

Installation and Configuration

MCP Settings

Add the following configuration to MCP settings:

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

storybook-mcp starts immediately and installs Chromium in the background the first time it runs. If you want to preinstall the browser ahead of time, run npx -y storybook-mcp@latest install-browser. Until that download finishes, the first browser-backed tool call can take longer.

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 provides built-in tools and supports custom tools:

Built-in Tools

1. getComponentList

Retrieves a list of all available components from the configured Storybook.

Example:

Copy code
Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

Gets 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:

Copy code
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:

typescriptCopy code
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:

jsonCopy code
[
  {
    "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.

Example

Set Spectrum storybook-mcp config with STORYBOOK_URL and CUSTOM_TOOLS environment variables.

jsonCopy code
{
  "mcpServers": {
    "storybook-mcp": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "https://opensource.adobe.com/spectrum-web-components/storybook/index.json",
        "CUSTOM_TOOLS": "[{\"name\":\"getIconList\",\"description\":\"Get All Icons from the Icon page\",\"parameters\":{},\"page\":\"https://opensource.adobe.com/spectrum-web-components/storybook/iframe.html?viewMode=docs&id=icons--docs&globals=\",\"handler\":\"Array.from(document.querySelector('icons-demo').shadowRoot.querySelectorAll('.icon')).map(i => i.textContent)\"}]"
      }
    }
  }
}

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 works 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: yarn install:browser
4. Set the environment variable: export STORYBOOK_URL="your-storybook-url"
5. Run in development mode: yarn dev

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

Building

bashCopy code
yarn build

Testing

bashCopy code
yarn test

Requirements

• Node.js 18.0.0 or higher
• Chromium browser installed by Playwright

Error Handling

The server includes 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.