@storybook/mcp weekly downloads statistics

Storybook MCP

Reusable MCP package for Storybook component and docs knowledge.

Learn more about Storybook at storybook.js.org.

Self-hosting @storybook/mcp

This package is a library: the tarball ships one module and no executable. It declares no bin, starts no process, and has no CLI. You register its tools on an MCP server you own, using the snippets below. If you want a running Storybook MCP server with no code at all, use the dev server instead — storybook dev serves one at /mcp through @storybook/addon-mcp.

Prerequisites

• Node.js 20+
• A manifests source containing:
  • components.json (required)
  • docs.json (optional)

Example implementation

The Storybook repository has a local HTTP server built on this package, serve.ts, that loads manifests from a directory or URL. It is a development harness and is not part of the published package.

The snippets below cover the common self-hosting patterns.

Minimal implementation

import { createStorybookMcpHandler } from '@storybook/mcp';

const storybookMcpHandler = await createStorybookMcpHandler();

export async function handleRequest(request: Request): Promise<Response> {
	if (new URL(request.url).pathname === '/mcp') {
		return storybookMcpHandler(request);
	}

	return new Response('Not found', { status: 404 });
}

With custom manifest source

Use manifestProvider when your manifests are not available from the same origin/path layout:

const storybookMcpHandler = await createStorybookMcpHandler({
	manifestProvider: async (_request, path) => {
		return asyncReadManifestFromSomewhere(path);
	},
});

API reference

createStorybookMcpHandler

Type:

(options?: StorybookMcpHandlerOptions) => Promise<Handler>;

type Handler = (req: Request, context?: StorybookContext) => Promise<Response>;

Creates and configures an MCP HTTP handler with all built-in docs tools registered.

Parameters

options

Type: StorybookMcpHandlerOptions

Default: {}

Server-level configuration. The handler uses this at creation time and as a fallback for per-request context.

Returns

Type: Promise<Handler>

A fetch-compatible request handler for your /mcp endpoint.

Behavior

• Registers these MCP tools:
  • docs-list
  • docs-show
  • docs-show-story
• Uses HTTP transport from @tmcp/transport-http.
• For each request, the handler always passes the current Request as context.request.
• Per-request context overrides handler-level options for:
  • manifestProvider
  • onListAllDocumentation
  • onGetDocumentation

Note: onSessionInitialize can only be set at handler creation time (in options).

Example

import { createStorybookMcpHandler } from '@storybook/mcp';

const mcp = await createStorybookMcpHandler({
	manifestProvider: async (_request, path) => {
		return await fetchManifest(path);
	},
});

export async function handleRequest(request: Request) {
	if (new URL(request.url).pathname !== '/mcp') {
		return new Response('Not found', { status: 404 });
	}

	return mcp(request);
}

Handler options and request context

@storybook/mcp uses the same core fields in two places:

• Handler creation (createStorybookMcpHandler(options))
• Per-request override (handler(request, context))

Type:

type StorybookContext = {
	request?: Request;
	manifestProvider?: (
		request: Request | undefined,
		path: string,
		source?: Source,
	) => Promise<string>;
	sources?: Source[];
	onListAllDocumentation?: (params: {
		context: StorybookContext;
		manifests: AllManifests;
		resultText: string;
		sources?: SourceManifests[];
	}) => void | Promise<void>;
	onGetDocumentation?: (
		params:
			| {
					context: StorybookContext;
					input: { id: string; storybookId?: string };
					foundDocumentation: ComponentManifest | Doc;
					resultText: string;
			  }
			| {
					context: StorybookContext;
					input: { id: string; storybookId?: string };
			  },
	) => void | Promise<void>;
};

type StorybookMcpHandlerOptions = StorybookContext & {
	onSessionInitialize?: (initializeRequestParams: InitializeRequestParams) => void | Promise<void>;
};

[!NOTE] onSessionInitialize is only used when provided at handler creation time (createStorybookMcpHandler(options)). It is ignored in per-request context.

InitializeRequestParams is the tmcp initialize payload type, and its exact structure may change in patch versions. Prefer treating it as an opaque protocol payload unless you need specific fields.

manifestProvider

Type:

(request: Request | undefined, path: string, source?: Source) => Promise<string>;

Primary extension point for production setups.

Use this when manifests are not available at the default same-origin paths. Your function returns the raw JSON string for each requested manifest path.

For a real customization example (switching between HTTP and filesystem-backed manifest loading), see the Example implementation section above.

Manifest paths requested by built-in tools:

• ./manifests/components.json (required)
• ./manifests/docs.json (optional)

request

Type: Request

The incoming HTTP request for the current call, as a Web Fetch API (WHATWG) Request.…