Registry / web-framework / storybook-mcp-server

storybook-mcp-server

JSON →
library0.1.3jsnpmunverified

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.

npm install storybook-mcp-server
INSTALL
IMPORT
SIG · STORYBOOK-MCP-SERV
S
storybook-mcp-server
web-frameworkjavascriptv0.1.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startServer
import { startServer } from 'storybook-mcp-server';
const startServer = require('storybook-mcp-server').startServer;
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
import { StorybookMcpServer } from 'storybook-mcp-server';
const StorybookMcpServer = require('storybook-mcp-server').StorybookMcpServer;
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.

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}.`); });
storybook-mcp-server --version
Debug
Known issues
breakingThe 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.
affects: <1.0.0
gotchastorybook-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.
affects: <=0.1.x
gotchaThe 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.
affects: >=0.1.0
gotchaThe 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`).
affects: >=0.1.0
Errors
Common errors & fixes
Error: Node.js version 16.x.x is not supported. Please use Node.js >= 18.0.0.
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
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.
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.
Upgrade
Version history
0.1.3latest on npm
Audit
Dependencies
puppeteerrequiredRequired for capturing screenshots and performing visual testing of Storybook stories.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources