Storybook MCP Integration
Use the Storybook MCP server (@storybook/addon-mcp) to give agents awareness of a project's actual component library — props, stories, tests, and live previews.
When to Use
- Component generation — check existing Storybook components before creating new ones
- Component testing — run story tests + a11y audits via MCP instead of CLI
- Visual verification — embed story previews in chat for user confirmation
- Component auditing — inventory components with full metadata via MCP
Quick Reference — 6 Tools, 3 Toolsets
| Toolset | Tool | Purpose | Key Inputs |
|---|---|---|---|
| dev | get-storybook-story-instructions | Guidance on writing stories + interaction tests | none |
| dev | preview-stories | Returns preview URLs for stories (embeddable) | stories[]: {storyId} or {absoluteStoryPath, exportName} |
| docs | list-all-documentation | Full component + docs manifest index | none |
| docs | get-documentation | Props, first 3 stories, story index, docs | id (required), storybookId (optional) |
| docs | get-documentation-for-story | Full story source + component docs | componentId, storyName (required) |
| testing | run-story-tests | Run component + a11y tests, pass/fail + violations | stories[] (optional), a11y boolean (default true) |
Prerequisites
# Storybook 10.3+ with Vite builder (no webpack)
npx storybook@latest upgrade
# Install the addon (current: @storybook/addon-mcp@0.6.0, Apr 2026)
npx storybook add @storybook/addon-mcp
# Enable docs toolset (required for component discovery)
# In .storybook/main.ts:
# componentsManifest: true
# NOTE: the old `experimentalComponentsManifest` flag was renamed in
# Storybook 10.3; it is now `componentsManifest` and default-on. Any
# code still passing the `experimental` prefix will warn-then-ignore.
# For Chromatic remote setups, use the standalone package instead of
# the addon (same tool surface, no local Storybook required):
# npm i -D @storybook/mcp
# npx storybook-mcp --registry https://chromatic.storybook.cloud
# Enable testing toolset (requires addon-vitest)
# npx storybook add @storybook/addon-vitest
# Register with Claude Code
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope projectDetection Pattern
Before using Storybook MCP tools, check availability:
# Probe for storybook-mcp tools
ToolSearch(query="+storybook list-all-documentation")
# If tools found → Storybook MCP is available
# If not found → fallback to filesystem-based component discoveryRule Details
Load rules on demand with Read("${CLAUDE_SKILL_DIR}/rules/<file>"):
| Rule | Impact | Description |
|---|---|---|
component-discovery | HIGH | Use list-all-documentation + get-documentation before generating new components |
story-preview-verification | HIGH | Embed preview-stories URLs for visual confirmation |
mcp-test-runner | CRITICAL | Run run-story-tests with a11y:true after component generation |
Toolset Selection
Filter toolsets via X-MCP-Toolsets header to reduce agent context:
| Agent Role | Toolsets | Rationale |
|---|---|---|
| component-curator | docs | Inventory + props only, no testing |
| frontend-ui-developer | dev,docs,testing | Full access for gen → verify loop |
| design-system-architect | docs | Component metadata for governance |
Chromatic Remote Publishing
For teams using Chromatic, the docs toolset is publishable remotely:
- Published at
https://<chromatic-storybook-url>/mcp - Only docs toolset available remotely (dev + testing need local Storybook)
- Useful for cross-team design system discovery without running Storybook locally
Graceful Degradation
| Storybook MCP | Fallback | Behavior |
|---|---|---|
| Available | — | Use MCP tools for component discovery, testing, previews |
| Unavailable | Filesystem | Glob("**/components/**/*.tsx") + Grep for component inventory |
| Unavailable | 21st.dev | Search public registry via 21st-dev-magic MCP |
| Unavailable | Manual | Claude multimodal analysis of screenshots |
Related Skills
storybook-testing— CSF3 patterns, Vitest integration, Chromatic TurboSnapcomponent-search— 21st.dev registry search (external components)design-to-code— Full mockup-to-component pipeline (uses this skill in Stage 2)ui-components— shadcn/ui + Radix component patterns