MCP Storybook Server

A Model Context Protocol (MCP) server that provides access to Storybook component documentation and props from Chromatic. This server connects to hosted Chromatic Storybook instances and provides tools to list components, get documentation, and extract component properties.

Features

• List Components: Get a simple list of all available components
• Component Documentation: Get detailed documentation for specific components
• Props Extraction: Extract component props/properties using Playwright browser automation
• Authentication Support: GitHub PAT and cookie-based authentication for Chromatic
• Dual Format Support: Supports both Storybook v3 and v5 formats
• Multiple Output Formats: Markdown and XML formatting options

Installation

# Install dependencies
npm install

# Install Playwright browsers (required for props scraping)
npx playwright install chromium

Configuration

Environment Variables

Create a .env file or set the following environment variables:

# Chromatic Storybook base URL (required)
STORYBOOK_URL=https://your-project.chromatic.com

# GitHub Personal Access Token for authentication (optional)
# Used for fetching index.json from Chromatic
GITHUB_PAT=your_github_pat_here

# Output format for documentation (markdown or xml, default: markdown)
STORYBOOK_FORMAT=markdown

# Playwright settings
PLAYWRIGHT_HEADLESS=true
PLAYWRIGHT_TIMEOUT=30000

# Chromatic cookies for authentication (optional)
# JSON string or cookie string format
CHROMATIC_COOKIES=

Cursor MCP Configuration

Add to your Cursor MCP config (.cursor/mcp.json or similar):

{
  "mcpServers": {
    "storybook": {
      "command": "node",
      "args": ["storybook/bin/mcp-storybook"],
      "env": {
        "STORYBOOK_URL": "https://your-project.chromatic.com",
        "GITHUB_PAT": "${GITHUB_PAT}",
        "STORYBOOK_FORMAT": "markdown"
      }
    }
  }
}

Available Tools

1. list-all-documentation

List all available UI components and documentation entries from the Storybook.

Example:

Tool: list-all-documentation

Returns a formatted list of all components with their IDs and descriptions.

2. get-documentation

Get detailed documentation for a specific UI component or docs entry by ID.

Parameters:

• id (string, required): Component or documentation entry ID

Example:

Tool: get-documentation
Parameters: { "id": "atoms-avatar" }

Returns detailed component documentation including stories, descriptions, and metadata.

3. get-component-list

Get a simple list of all component names from the configured Storybook (fast, simple output).

Example:

Tool: get-component-list

Returns a simple list of component names.

4. get-component-props

Get props information for multiple components using Playwright to scrape from Chromatic pages.

Parameters:

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

Example:

Tool: get-component-props
Parameters: { "componentNames": ["Avatar", "Button", "Input"] }

Returns props tables for each component, including:

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

Note: This tool requires Playwright and will launch a headless browser to scrape props from Chromatic pages.

Authentication

For private Chromatic Storybooks (especially with GitHub SSO), you need to provide authentication. The server supports multiple authentication methods:

Option 1: Chromatic Project Token (Recommended - Most Permanent)

Chromatic project tokens don't expire and are the best option for long-term use:

1. Go to your Chromatic project → Manage → Configure
2. Find your Project Token
3. Set it as CHROMATIC_PROJECT_TOKEN environment variable

Note: Project tokens may work for API access but might not work for UI-based Storybook access. If it doesn't work, use cookies (Option 2).

Option 2: Chromatic Cookies (Required for Private Storybooks with SSO)

Session cookies are required for accessing private Storybooks. ⚠️ Important: Cookies expire when your Chromatic session expires (typically after inactivity or logout).

Quick Cookie Extraction

Use the helper script to format cookies:

node scripts/extract-cookies.js

Then follow the prompts to paste your cookies.

Manual Cookie Extraction

⚠️ Important: Chromatic cookie names can vary. Look for cookies with long, random values (not simple values like true or 1).

Step-by-step:

1. Log in to Chromatic in your browser
2. Open DevTools (F12) → Application (Chrome) or Storage (Firefox)
3. Go to Cookies → https://your-project.chromatic.com
4. Look for authentication cookies - Common names include:
   • __session (most common)
   • chromatic_session
   • auth or auth_token
   • __chromatic_auth
   • Any cookie with a long, random-looking value (like eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...)
5. Copy the Name and Value for each authentication cookie
6. Use one of these formats:

📖 For detailed step-by-step instructions with screenshots, see COOKIE_EXTRACTION_GUIDE.md

JSON Array Format (example with __session cookie):

[
  {
    "name": "__session",
    "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "domain": ".chromatic.com",
    "path": "/"
  }
]

If you have multiple cookies:

[
  {
    "name": "__session",
    "value": "abc123...",
    "domain": ".chromatic.com",
    "path": "/"
  },
  {
    "name": "auth_token",
    "value": "xyz789...",
    "domain": ".chromatic.com",
    "path": "/"
  }
]

Cookie String Format:

__session=abc123...; auth_token=xyz789...

💡 Don't know which cookies to use? Copy ALL cookies from the Chromatic domain and test them. The authentication will work if you include the right ones.

Cookie Expiration & Refresh

Cookies expire when:

• Your Chromatic session expires (after inactivity)
• You log out of Chromatic
• Your session is invalidated

When cookies expire, you'll see:

Error: Unauthorized: Invalid or missing authentication credentials

To refresh cookies:

1. Log in to Chromatic again in your browser
2. Extract cookies using the steps above
3. Update CHROMATIC_COOKIES in your MCP config
4. Restart Cursor/MCP client

Tip: Consider using a browser extension like "Cookie-Editor" to quickly export cookies when needed.

Option 3: GitHub PAT (Limited Support)

Set the GITHUB_PAT environment variable. This may work for some Chromatic setups but is not reliable for private Storybooks with GitHub SSO.

How It Works

1. Component List: The server fetches the Storybook's index.json file and extracts component information
2. Documentation: Transforms index.json entries into structured ComponentManifest format
3. Props Information: For component props, the server:
   • Finds the component's story ID from index.json
   • Constructs the Chromatic story URL: {STORYBOOK_URL}/?path=/story/{storyId}
   • Uses Playwright to load the page in a headless browser
   • Extracts the props table from the Controls tab
   • Returns the props information

Supported Storybook URLs

The server works with Chromatic-hosted Storybook instances that expose an index.json file. The URL should point to the base Chromatic URL:

• https://your-project.chromatic.com
• https://your-project.chromatic.com/index.json

Testing Authentication Locally

Before using the MCP server, you can test authentication locally:

# Set your environment variables
export STORYBOOK_URL="https://your-project.chromatic.com"
export CHROMATIC_COOKIES='[{"name":"session","value":"..."}]'

# Or use project token
export CHROMATIC_PROJECT_TOKEN="your-project-token"

# Run the test
npm run test:auth

This will test:

• ✅ Configuration loading
• ✅ Authentication methods (Project Token, Cookies, GitHub PAT)
• ✅ Fetching index.json from Chromatic
• ✅ Authentication headers

See TESTING.md for detailed testing instructions.

Development

Local Development

# Install dependencies
npm install

# Install Playwright browsers
npx playwright install chromium

# Build the project
npm run build

# Run in development mode
npm run dev

# Test authentication locally
npm run test:auth

# Type check
npm run typecheck

# Lint
npm run lint

Building

npm run build

Testing

npm 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
• Authentication failures (401, 403, redirects)
• Component not found scenarios
• Playwright browser automation failures
• Malformed index.json responses

Architecture

The server follows the same architecture pattern as other MCP servers in this workspace:

• Main entry: src/index.ts - Server initialization
• Tools: src/tools/index.ts - MCP tool implementations
• Configuration: src/config/ - Environment variable handling
• Types: src/types/ - TypeScript type definitions
• Utilities: src/utils/ - Manifest fetching, formatting, authentication, Playwright

Key Features

• ✅ Supports both Storybook v3 and v5 formats
• ✅ GitHub PAT authentication for index.json fetching
• ✅ Cookie-based authentication for Playwright
• ✅ Dual approach: simple component list + structured documentation
• ✅ Playwright-based props scraping from Chromatic pages
• ✅ Markdown and XML output formats
• ✅ Comprehensive error handling

License

MIT

Repository

Part of the mcp-servers monorepo.