{"id":14941,"library":"storybook-mcp-server","title":"Storybook MCP Server","description":"storybook-mcp-server is a TypeScript-based Model Context Protocol (MCP) server that enables AI assistants to interact comprehensively with Storybook instances. It allows AI agents to discover components, list and filter stories, retrieve detailed story information (including props and args), and capture screenshots across various viewports. The current stable version is 0.1.3, indicating it's in early development with a focus on feature completion and documentation. Release cadence appears to be driven by documentation updates and initial feature set completion rather than strict timeboxes, with all releases to date being pre-1.0. Key differentiators include its adherence to the MCP standard, direct integration with Storybook for metadata extraction, and leveraging Puppeteer for robust visual testing capabilities, making it a specialized tool for AI-driven component interaction and analysis.","status":"active","version":"0.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/stefanoamorelli/storybook-mcp-server","tags":["javascript","mcp","mcp-server","storybook","model-context-protocol","claude","claude-desktop","anthropic","puppeteer","typescript"],"install":[{"cmd":"npm install storybook-mcp-server","lang":"bash","label":"npm"},{"cmd":"yarn add storybook-mcp-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add storybook-mcp-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for capturing screenshots and performing visual testing of Storybook stories.","package":"puppeteer","optional":false}],"imports":[{"note":"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.","wrong":"const startServer = require('storybook-mcp-server').startServer;","symbol":"startServer","correct":"import { startServer } from 'storybook-mcp-server';"},{"note":"Assumed class for programmatic server instance management or direct interaction. The specific class name and availability are subject to verification.","wrong":"const StorybookMcpServer = require('storybook-mcp-server').StorybookMcpServer;","symbol":"StorybookMcpServer","correct":"import { StorybookMcpServer } from 'storybook-mcp-server';"},{"note":"Type definition for configuring the MCP server programmatically. Useful for defining server behavior when not using CLI arguments. Subject to verification.","symbol":"ServerConfig","correct":"import type { ServerConfig } from 'storybook-mcp-server';"}],"quickstart":{"code":"import { exec } from 'child_process';\nimport path from 'path';\n\n// IMPORTANT: Ensure your Storybook is running before starting the MCP server.\n// For example, run `npm run storybook` in your project, typically on http://localhost:6006.\nconsole.log('--- Starting Storybook MCP Server Quickstart ---');\nconsole.log('Please ensure your Storybook is running, e.g., on http://localhost:6006');\n\nconst storybookUrl = process.env.STORYBOOK_URL ?? 'http://localhost:6006';\nconst outputDir = path.resolve(process.cwd(), './mcp-screenshots');\n\nconsole.log(`Configured to connect to Storybook at: ${storybookUrl}`);\nconsole.log(`Screenshots will be saved to: ${outputDir}`);\n\nconst command = `storybook-mcp-server --storybook-url ${storybookUrl} --output-dir ${outputDir}`;\n\nconsole.log(`Executing command: ${command}\\n`);\n\n// Execute the CLI command as a child process\nconst childProcess = exec(command, (error, stdout, stderr) => {\n  if (error) {\n    console.error(`Error starting MCP server: ${error.message}`);\n    console.error(`Stderr: ${stderr}`);\n    return;\n  }\n  console.log(`MCP Server Stdout: ${stdout}`);\n  if (stderr) {\n    console.warn(`MCP Server Stderr: ${stderr}`);\n  }\n  console.log('\\nStorybook MCP Server started successfully (or is attempting to connect).');\n  console.log('An AI assistant (e.g., Anthropic Claude) can now connect and interact via the Model Context Protocol.');\n  console.log('Example prompt for AI: \"What components are available in my Storybook?\"');\n  console.log('To stop the server, you would typically kill this process.');\n});\n\n// Optional: Add a listener for process exit for cleanup or logging\nchildProcess.on('exit', (code) => {\n  console.log(`\\nStorybook MCP Server process exited with code ${code}.`);\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Refer to the latest release notes and official documentation for API changes when upgrading to new versions.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<=0.1.x"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Before starting `storybook-mcp-server`, ensure your Storybook application is running and accessible at the URL you provide (e.g., `http://localhost:6006`).","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade your Node.js environment to version 18 or higher. For example, using `nvm`: `nvm install 18 && nvm use 18`.","cause":"Attempting to run `storybook-mcp-server` with an unsupported Node.js version (e.g., 16.x).","error":"Error: Node.js version 16.x.x is not supported. Please use Node.js >= 18.0.0."},{"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.","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`).","error":"Error: connect ECONNREFUSED ::1:6006"},{"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.","cause":"Puppeteer, a dependency for capturing screenshots, could not locate a compatible browser executable on the host system.","error":"Error: Could not find Chromium (or Chrome) in your system."}],"ecosystem":"npm"}