Storybook MCPサーバーをClaude Codeに繋ぐ手順とフレームワーク対応

Storybookは公式のMCPサーバーを持っており、Claude CodeにコンポーネントカタログとドキュメントをMCP経由で読ませられます。既存のコンポーネントを再利用したUI生成、生成したUIのストーリー作成、インタラクションテストの実行までを1つのMCPサーバーで扱う設計です。この機能はプレビュー段階にあり、APIは今後変わる可能性があります。

MCPプロトコル自体の仕組みはMCPとは、デザインファイルからのコード生成を扱うFigma MCPサーバーの使い方とは役割が異なります。

Storybook MCPサーバーとは

Storybook MCPサーバーとは、実行中のStorybookをAIエージェントに繋ぐ公式MCPサーバーです。エージェントにコンポーネントの仕様・使用例・ドキュメントを理解させ、ストーリー生成やテスト実行までを任せられます。テストで問題が見つかれば、エージェント自身が修正して再実行する「自己修復ループ」を作れる点が設計の中心です。

サーバーの実体は、Storybookの開発サーバーに載るアドオン(@storybook/addon-mcp)です。Storybookを起動している間だけ/mcpのエンドポイントが生きるので、Claude Code側は「ローカルで動くHTTPサーバーを1本追加する」だけの構成になります。

自分のプロジェクトでdocsツールが使えるか

MCPサーバー自体はすべてのStorybookプロジェクトで動きます。ただし、コンポーネントの仕様を読ませる「docsツールセット」だけは、componentsManifestというJSON形式のメタデータを生成できるフレームワークに限られます。

AngularのviteビルドはexperimentalDocgenServerを自分で有効にするので、設定するのはcomponentsManifestだけです。Vueは既定でその機能が切れているため、@storybook/vue3-viteでは2つとも書きます。@nuxtjs/storybookのようにvue3-vite以外のVue構成は、コンポーネントのマニフェストを生成しません。

マニフェスト非対応の環境でも、ストーリーの生成・プレビュー・テスト実行を扱うdevelopmentとtestingの2ツールセットは動きます。使えないのはdocsツールセットだけです。

導入手順

1. アドオンをインストールする

npx storybook add @storybook/addon-mcp

Storybookの開発サーバーを起動すると、http://localhost:6006/mcp(ポート番号は環境による)でMCPサーバーが立ち上がります。ブラウザでこのURLを開くと、利用可能なツール一覧とマニフェストデバッガーへのリンクが表示されます。

2. componentsManifestを有効化する(docsツールセットを使う場合)

.storybook/main.tsでcomponentsManifestを有効にします。既定ではオフです。

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  features: {
    componentsManifest: true,
  },
};
 
export default config;

対応フレームワークの表にない環境ではこの設定は効かず、docsツールセットは利用不可のまま、developmentとtestingの2ツールセットだけが使える状態になります。

3. Claude CodeにMCPサーバーを追加する

claude mcp add --scope project --transport http storybook http://localhost:6006/mcp

Claude Code v2.1.287で、空のディレクトリを使ってこのコマンドを実行すると、次の出力になりました。

Added HTTP MCP server storybook with URL: http://localhost:6006/mcp to project config
File modified: <作業ディレクトリ>/.mcp.json

作られた.mcp.jsonの中身は次の8行です。

{
  "mcpServers": {
    "storybook": {
      "type": "http",
      "url": "http://localhost:6006/mcp"
    }
  }
}

--transportを付けない場合、claude mcp add --helpの記述では既定がstdioです。HTTPのURLを渡すなら--transport httpは省けません。ポート番号は実際に起動しているStorybookのものに置き換えます。

--scopeはlocal(既定)・user・projectから選びます。ここでprojectを選んだ理由は、次の比較のとおりです。

プロジェクトスコープのサーバーは、追加した直後には使えません。同じディレクトリでclaude mcp get storybookを実行すると、次の表示でした。

storybook:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: http
  URL: http://localhost:6006/mcp

Pending approvalは、.mcp.jsonに書かれたサーバーをまだ承認していない状態です。claudeを対話モードで起動して承認するまで、接続もヘルスチェックもされません。チームの誰かがコミットした.mcp.jsonを取り込んだ側でも、同じ承認が1回必要になります。

4. CLAUDE.mdでエージェントの振る舞いを指定する

MCPサーバーを追加しただけでは、Claudeが自発的にツールを使うとは限りません。Storybookの公式ドキュメントは、AGENTS.md(Claudeを使うならCLAUDE.md)に次のような指示を書くことを勧めています。your-project-sb-mcpの部分は、手順3で付けたサーバー名(この記事の例ではstorybook)に置き換えます。

When working on UI components, always use the `your-project-sb-mcp` MCP tools to access Storybook's component and documentation knowledge before answering or taking any action.
 
- **CRITICAL: Never hallucinate component properties!** Before using ANY property on a component from a design system (including common-sounding ones like `shadow`, etc.), you MUST use the MCP tools to check if the property is actually documented for that component.
- Query `docs-list` to get a list of documented components
- Query `docs-show` for that component to see all available properties and examples
- Only use properties that are explicitly documented or shown in example stories
- If a property isn't documented, do not assume properties based on naming conventions or common patterns from other libraries. Check back with the user in these cases.
- Use the `get-storybook-story-instructions` tool to fetch the latest instructions for creating or updating stories. This will ensure you follow current conventions and recommendations.
- Check your work by running `test-run`.
 
Remember: A story name might not reflect the property name correctly, so always verify properties through documentation or example stories before using them.

書き換えるときに残したいのは3点です。docsツールセットでプロパティを確認させること、ストーリーの書き方をget-storybook-story-instructionsで毎回取らせること、最後にtest-runを走らせることです。shadowのように一般的に聞こえるプロパティでも、実際にドキュメント化されているかを必ず確かめさせる点が、存在しないプロパティを使ったコードを防ぎます。

CLAUDE.mdを整えたら、Storybookを起動した状態で「List all documented components」のようなプロンプトを送ります。docs-listツールの呼び出しと、Storybookのコンポーネント一覧が返れば接続できています。

ツールが出る条件はツールセットごとに違う

Storybook MCPサーバーのツールは、development・docs・testingの3つのツールセットに分かれます。ツールセットの名前だけでなく、各ツールには「出るための条件」があります。

stories-previewは、接続しているエージェントがMCP Appsに対応していればチャット内にプレビューを表示し、対応していなければStorybook上のリンクを返します。ピクセル単位のビジュアル回帰まで確認したい場合は、Claude CodeでChromaticのビジュアルテストを回すのようにChromaticと組み合わせる方法もあります。

不要なツールセットは、アドオンのオプションで切れます。.storybook/main.tsのaddonsに、名前とオプションを渡す形で書きます。

addons: [
  {
    name: '@storybook/addon-mcp',
    options: {
      toolsets: {
        dev: false, // developmentツールセットを無効化
      },
    },
  },
],

toolsetsにはdev・docs・testの3つのキーがあり、既定はすべてtrueです。docsとtestはキーがあっても、componentsManifestやaddon-vitestが無ければ、そもそもツールが出ません。

典型的な流れ: ログインフォームの生成

3つのツールセットは、組み合わせたときに効きます。公式ドキュメントが示す典型例が、「ログインフォームを作って」というプロンプトです。

公式には、ほかに3つの使い方が載っています。「ダークモードのButtonを見せて」は、developmentツールセットでプレビューを返す使い方です。「Headerを含むストーリーを全部テストして」では、ファイル検索でHeaderを使うコンポーネントを特定してからtest-runを走らせます。「ログインフォームの送信を確かめるストーリーを書いて」は、play関数でユーザー操作を再現するストーリーを書かせる例です。

テストの再実行まで任せられる点が、コードを出して終わるAIツールとの違いです。

マニフェストに載せるものを選ぶ

docsツールセットの中身は、Storybookが組み立てるマニフェストです。何が入っているかは、開発サーバーが動いているとき、次のURLで確認できます(ポートは環境による)。

デバッガーの上部には、マニフェストの生成中に出たエラーと警告が並びます。ボタンで該当のエントリだけに絞れるので、「このコンポーネントがdocs-listに出ない」ときの最初の確認先です。

エージェントに見せたくないストーリーは、manifestタグで外せます。既定ではすべてのストーリーと独立したドキュメントページにこのタグが付いており、tags: ['!manifest']でそのストーリーだけを除外できます。ファイルのメタ(default export)で外せば、そのファイルの全ストーリーが対象になります。「教材用のストーリー」や「人間向けの説明ページ」を除く用途です。

コンポーネントのprops情報は、JSDocコメントがあるとマニフェストに説明として載ります。Storybookの公式ドキュメントも、コンポーネントとpropsにJSDocを書くことを強く勧めています。docsツールセットが返す情報の質は、ここで決まります。

Figma MCPとの役割の違い

Figma MCPサーバーとStorybook MCPサーバーは、どちらもUI開発向けですが、見ているものが違います。Figma MCPはデザインファイルを読んでコード生成の入口になり、Storybook MCPは既存のコンポーネントとデザインシステムを読む側です。

両方を繋ぐと、Figmaの内容をStorybookのコンポーネントに寄せてコードを書かせる構成が考えられます。ただし、2つを連携させる手順はStorybook側の公式ドキュメントに載っていません。Reactのデザインシステムをコードベースと同期させる別のアプローチはClaude Code design-syncの使い方でも扱っています。

よくあるつまずき

docsツールセットが「利用不可」と表示される

フレームワークがcomponentsManifestに対応していないか、対応していてもcomponentsManifest機能フラグが有効になっていないかのどちらかです。まず対応フレームワークの表で自分の環境を確認し、対応している場合はmain.tsの設定を見直します。

claude mcp getが「Pending approval」のまま

プロジェクトスコープで追加した直後は、この表示が正常です。claudeを対話モードで起動し、.mcp.jsonのサーバーを承認すると接続されます。リポジトリ側の.claude/settings.jsonにenableAllProjectMcpServersなどを書いても、未信頼のフォルダでは無視されてPending approvalのままです(v2.1.196以降)。承認の選択をやり直すときはclaude mcp reset-project-choicesを使います。

experimentalDocgenServer有効時にマニフェストのJSONルートが404になる

experimentalDocgenServerを有効にしていると、開発サーバーはcomponents.jsonとdocs.jsonの両方のJSONルートに対して404を返す仕様です。これはバグではなく、マニフェストがディスクに書き出されずdocgenサービスからオンデマンドで組み立てられる方式に変わるためです。@storybook/angular-viteと@storybook/vue3-viteでは常にこの挙動になり、Reactプロジェクトでは機能を有効にした場合のみ発生します。生成済みのStorybookビルドから読むか、デバッガーのページを使います。

複数のStorybookを合成しているのに一部のコンポーネントが見えない

StorybookのComposition機能では、複数のStorybookを1つに結合できます。このとき、取り込まれる側のStorybookがマニフェストを持っている場合だけ、その内容がMCPサーバーの応答に含まれます。取り込まれる側それぞれで、componentsManifestが有効になっているかを確認します。

エージェントがMCPツールを使ってくれない

CLAUDE.mdにMCPツールの利用を指示する記述が無いと、ツールを呼ばずにコードを書き始めることがあります。ツール名を含めて「UIコンポーネントを扱うときは必ずyour-project-sb-mcpのツールを使う」のように、名前を明示して書き込みます。

対応するAIエージェント

Storybook MCPサーバーは標準のMCPプロトコルに準拠しているため、Claude Code以外からも接続できます。公式ドキュメントが挙げているのは、Claude Code・OpenAI Codex・Cursor・Google Gemini CLI・VS Code Copilotなどです。

追加の方法は、Storybook側の手順と、Claude Code側の手順の2系統があります。Storybookの公式手順は、サードパーティ製CLIのmcp-addを使います。npx mcp-add --type http --url "http://localhost:6006/mcp" --scope projectを実行すると、サーバー名を対話的に聞かれます。Claude Codeだけで足りるなら、本記事のclaude mcp addがそのまま使えます。複数のエージェントを併用するチームでは、エージェントごとの設定差分を吸収できるmcp-addが便利です。

まとめ

Storybook MCPのつまずきは、docsツールセットが出るかどうかと、プロジェクトスコープのサーバーを承認したかどうかの2点にほぼ集まります。先に自分のフレームワークの対応表を確かめ、.mcp.jsonで共有するなら承認の1回を忘れないことです。プレビュー機能なので、アップデートのたびにCLAUDE.mdが古いツール名を指していないかを見直す必要があります。