Storybook MCP Server

Common errors

• Error: Node.js version 16.x.x is not supported. Please use Node.js >= 18.0.0.

  cause Attempting to run `storybook-mcp-server` with an unsupported Node.js version (e.g., 16.x).
  fix Upgrade your Node.js environment to version 18 or higher. For example, using `nvm`: `nvm install 18 && nvm use 18`.

• Error: connect ECONNREFUSED ::1:6006

  cause The `storybook-mcp-server` failed to establish a connection to the Storybook instance, typically because Storybook is not running or is inaccessible at the specified address (e.g., `localhost:6006`).
  fix Ensure your Storybook development server is actively running and accessible from where you're running the MCP server. Verify the `--storybook-url` argument matches your Storybook's actual address.

• Error: Could not find Chromium (or Chrome) in your system.

  cause Puppeteer, a dependency for capturing screenshots, could not locate a compatible browser executable on the host system.
  fix Install Google Chrome or Chromium on your system. For server environments, ensure that all headless browser dependencies are installed. In some cases, setting the `PUPPETEER_EXECUTABLE_PATH` environment variable might be necessary if the browser is in a non-standard location.

Warnings

• breaking The package is currently in early development (v0.1.x), which implies the API is not yet stable. Breaking changes may be introduced in minor or even patch releases prior to reaching a 1.0.0 stable version.
  Fix: Refer to the latest release notes and official documentation for API changes when upgrading to new versions.
• gotcha storybook-mcp-server requires Node.js version 18 or greater as specified in its `engines` field. Running the server with older Node.js versions will result in an error or undefined behavior.
  Fix: Ensure your Node.js environment is updated to version 18 or higher. Utilize a Node.js version manager like `nvm` to easily manage and switch between Node.js versions.
• gotcha The package relies on Puppeteer for screenshot capabilities, which in turn requires a Chromium or compatible browser (like Google Chrome or Edge) to be installed and accessible on the system. If Puppeteer cannot find or launch a browser, visual testing features will fail.
  Fix: Verify that a compatible browser is installed on your system. For headless or CI/CD environments, ensure all necessary system dependencies for Puppeteer are present. Consult Puppeteer's troubleshooting guide for common browser launch issues.
• gotcha The MCP server requires a running Storybook instance to connect to. If the provided `--storybook-url` is incorrect, or the target Storybook server is not active or reachable, the MCP server will fail to initialize or fetch component data.
  Fix: Before starting `storybook-mcp-server`, ensure your Storybook application is running and accessible at the URL you provide (e.g., `http://localhost:6006`).

Install

• npm install storybook-mcp-server npm
• yarn add storybook-mcp-server yarn
• pnpm add storybook-mcp-server pnpm

Imports

• startServer
  wrong:

  const startServer = require('storybook-mcp-server').startServer;

  correct:

  import { startServer } from 'storybook-mcp-server';

  Assumed programmatic entry point for starting the MCP server. While the primary interaction is via CLI, the package ships TypeScript types, implying a programmatic API. The exact function name and export path are subject to verification.
• StorybookMcpServer
  wrong:

  const StorybookMcpServer = require('storybook-mcp-server').StorybookMcpServer;

  correct:

  import { StorybookMcpServer } from 'storybook-mcp-server';

  Assumed class for programmatic server instance management or direct interaction. The specific class name and availability are subject to verification.
• ServerConfig

  import type { ServerConfig } from 'storybook-mcp-server';

  Type definition for configuring the MCP server programmatically. Useful for defining server behavior when not using CLI arguments. Subject to verification.

Quickstart

Demonstrates how to launch the `storybook-mcp-server` as a command-line utility, connecting it to a specified Storybook instance and configuring an output directory for captured screenshots. This showcases the primary way developers interact with the server, enabling AI assistants to access Storybook content.

import { exec } from 'child_process';
import path from 'path';

// IMPORTANT: Ensure your Storybook is running before starting the MCP server.
// For example, run `npm run storybook` in your project, typically on http://localhost:6006.
console.log('--- Starting Storybook MCP Server Quickstart ---');
console.log('Please ensure your Storybook is running, e.g., on http://localhost:6006');

const storybookUrl = process.env.STORYBOOK_URL ?? 'http://localhost:6006';
const outputDir = path.resolve(process.cwd(), './mcp-screenshots');

console.log(`Configured to connect to Storybook at: ${storybookUrl}`);
console.log(`Screenshots will be saved to: ${outputDir}`);

const command = `storybook-mcp-server --storybook-url ${storybookUrl} --output-dir ${outputDir}`;

console.log(`Executing command: ${command}\n`);

// Execute the CLI command as a child process
const childProcess = exec(command, (error, stdout, stderr) => {
  if (error) {
    console.error(`Error starting MCP server: ${error.message}`);
    console.error(`Stderr: ${stderr}`);
    return;
  }
  console.log(`MCP Server Stdout: ${stdout}`);
  if (stderr) {
    console.warn(`MCP Server Stderr: ${stderr}`);
  }
  console.log('\nStorybook MCP Server started successfully (or is attempting to connect).');
  console.log('An AI assistant (e.g., Anthropic Claude) can now connect and interact via the Model Context Protocol.');
  console.log('Example prompt for AI: "What components are available in my Storybook?"');
  console.log('To stop the server, you would typically kill this process.');
});

// Optional: Add a listener for process exit for cleanup or logging
childProcess.on('exit', (code) => {
  console.log(`\nStorybook MCP Server process exited with code ${code}.`);
});