mcpland

Storybook MCP Server

Community mcpland
Updated

A Model Context Protocol (MCP) server for Storybook.

Storybook MCP Server

Node CInpmlicense

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:

{
  "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 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:

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:

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.

Example

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

{
  "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: npx playwright install chromium
  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

yarn build

Testing

yarn test

Requirements

  • Node.js 18.0.0 or higher
  • Chromium browser (automatically installed with 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.

MCP Server ยท Populars

MCP Server ยท New