Storybook MCP로 AI에게 컴포넌트 맥락 알려주기

AI 코딩 에이전트에게 UI를 만들어달라고 하면 종종 난감한 결과물이 나옵니다. 프로젝트에 이미 잘 만들어둔 Button, Card, Modal 같은 컴포넌트가 있는데 에이전트는 그 존재를 모르니까 비슷한 걸 또 만들어버리는 거죠. 디자인 시스템을 열심히 구축해놨는데 AI가 인라인 스타일로 대충 때운 컴포넌트를 내놓으면 정말 답답합니다 😅

이 문제의 원인은 간단합니다. AI 에이전트에게 우리 프로젝트의 UI 컴포넌트에 대한 맥락이 없기 때문인데요. Storybook이 MCP(Model Context Protocol)를 통해 이 문제를 정면으로 해결하려 나섰습니다.

이번 글에서는 Storybook MCP가 어떻게 동작하는지 파악하고, 직접 프로젝트에 붙여보겠습니다.

Storybook MCP란?

Storybook MCP는 AI 에이전트에게 프로젝트의 React 컴포넌트 정보를 전달하는 MCP 서버입니다. Storybook 10.3에서 React 프로젝트용으로 처음 출시되었어요.

기존에 AI 에이전트가 UI를 생성할 때 겪는 핵심 문제가 뭐냐면, 에이전트가 프로젝트에 어떤 컴포넌트가 있는지 전혀 모른다는 겁니다. 소스 코드를 읽을 수는 있지만 각 컴포넌트가 어떻게 렌더링되는지, 어떤 props를 받는지, 어떤 변형(variant)이 있는지까지 파악하기는 어렵죠.

Storybook MCP는 이미 Storybook에 정리해둔 스토리, API 문서, 컴포넌트 메타데이터를 MCP 프로토콜로 AI 에이전트에게 전달합니다. 에이전트가 “이 프로젝트에 버튼 컴포넌트가 있어?”라고 물으면 Storybook이 해당 컴포넌트의 props, 스토리, 사용 예시를 알려주는 식이에요.

왜 필요한가

“에이전트가 소스 코드를 직접 읽으면 되는 거 아닌가?” 하고 생각할 수 있는데요. 실제로 해보면 소스 코드만으로는 부족한 경우가 많습니다.

우선 컴포넌트가 실제로 어떻게 보이는지는 코드만 봐서는 알기 어렵습니다. CSS 변수, 테마, 반응형 레이아웃 같은 게 복합적으로 적용되기 때문이죠. Storybook의 스토리는 컴포넌트를 로딩, 에러, 빈 상태 등 여러 상태로 렌더링한 결과를 담고 있어서 에이전트에게 훨씬 풍부한 맥락을 줍니다.

디자인 시스템을 여러 팀이 공유하는 경우도 있는데요. 핵심 UI 라이브러리는 A팀이 만들고 제품에서는 B팀이 쓰는 식인데, 에이전트가 A팀의 Storybook까지 참고해야 제대로 된 코드를 작성할 수 있거든요. Storybook MCP는 여러 Storybook을 합성(composition)해서 하나의 맥락으로 에이전트에게 전달하는 것도 지원합니다.

벤치마크 결과도 꽤 인상적입니다. Storybook MCP를 적용했을 때 기존 컴포넌트 재사용률이 12.8% 향상되었고, 코드 생성 속도는 2.76배 빨라졌으며, 토큰 사용량은 27% 줄었다고 해요. 기존 컴포넌트를 가져다 쓰니 코드를 처음부터 생성하는 것보다 빠르고 저렴한 건 당연하겠죠.

설치하기

Storybook MCP를 사용하려면 먼저 Storybook을 10.3 이상으로 업그레이드해야 합니다.

bunx storybook@latest upgrade

그다음 MCP 애드온을 설치합니다.

bunx storybook add @storybook/addon-mcp

마지막으로 AI 클라이언트에 MCP 서버를 등록합니다. Storybook 개발 서버가 실행 중일 때 localhost:6006/mcp 엔드포인트로 접속할 수 있어요.

bunx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

이렇게 세 단계면 설치가 끝납니다.

AI 도구에서 연결하기

Storybook MCP 서버는 로컬 개발 서버 위에서 동작하기 때문에 Storybook을 띄운 상태에서 AI 도구에 연결합니다.

클로드 코드에서는 CLI로 바로 추가할 수 있습니다.

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

팀 프로젝트에서 모든 개발자가 같은 설정을 쓰게 하려면 .mcp.json 파일을 Git으로 관리하는 것도 좋습니다.

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

Cursor에서는 .cursor/mcp.json에 추가하고, VS Code에서는 .vscode/mcp.json에 추가하면 됩니다.

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

컴포넌트 재사용 강제하기

Storybook MCP가 연결되면 AI 에이전트는 코드를 생성하기 전에 먼저 프로젝트에 어떤 컴포넌트가 있는지 확인합니다. “사용자 프로필 카드를 만들어줘”라고 요청하면 에이전트가 Storybook에서 Card, Avatar, Badge 같은 기존 컴포넌트를 찾아서 이것들을 조합하여 작성하는 거죠.

MCP 서버가 각 컴포넌트의 props 타입, 기본값, variant, 실제 스토리 코드까지 전달하기 때문에 가능한 일입니다. 단순한 컴포넌트 목록이 아니라 Storybook에 작성해둔 docs 페이지나 JSDoc 주석도 함께 넘어가요. “이 컴포넌트는 이런 상황에서 쓰고 이런 상황에서는 다른 컴포넌트를 쓰세요” 같은 가이드라인까지 에이전트가 참고하게 되는 셈입니다.

라이브 스토리 프리뷰

Storybook MCP의 매력적인 기능 중 하나가 라이브 스토리 프리뷰입니다. 에이전트가 코드를 생성하면 그 결과물이 Storybook 스토리로 만들어져서 AI 채팅 인터페이스 안에서 바로 렌더링됩니다.

코드 리뷰를 할 때 diff만 보면서 “이게 실제로 어떻게 보일까?” 추측하지 않아도 됩니다. 생성된 컴포넌트가 렌더링된 모습을 바로 확인하고, 호버 상태나 클릭 인터랙션까지 채팅 안에서 테스트해볼 수 있거든요. 더 자세히 보고 싶으면 Storybook으로 이동하는 링크도 제공됩니다.

이건 MCP Apps라는 기능을 통해 구현되는데요. MCP 서버가 단순히 텍스트 데이터만 주고받는 게 아니라 인터랙티브한 UI를 클라이언트에 삽입할 수 있는 프로토콜 확장입니다.

자체 검증 테스트

에이전트가 컴포넌트를 만들기만 하고 끝이 아닙니다. Storybook MCP를 통해 에이전트가 직접 테스트를 실행하고 결과를 확인할 수 있어요.

에이전트가 새로운 컴포넌트를 생성하면 자동으로 컴포넌트 테스트와 접근성(a11y) 테스트를 돌립니다. 테스트가 실패하면 에이전트가 알아서 원인을 파악하고 수정을 시도하죠. 정말로 사람의 판단이 필요한 경우에만 개발자에게 알림을 보냅니다.

테스트 결과는 Storybook UI에도 실시간으로 표시되어서 에이전트가 어떤 테스트를 돌렸고 어디서 실패했는지 한눈에 볼 수 있습니다. 이 자체 검증 루프 덕분에 에이전트가 생성한 코드의 품질을 자동으로 보장할 수 있게 되는 건데요. MCP의 양방향 통신이 있어야 가능한 기능이라서 단순히 프롬프트에 지침을 넣는 것과는 차원이 다릅니다.

멀티 Storybook 합성

대규모 프로젝트에서는 Storybook이 여러 개인 경우가 많습니다. 디자인 시스템팀의 Storybook, 제품팀의 Storybook, 서드파티 라이브러리의 Storybook이 각각 따로 있을 수 있거든요.

Storybook MCP는 이런 여러 Storybook을 하나로 합성하여 에이전트에게 전달하는 기능을 제공합니다. 에이전트가 여러 MCP 서버에 각각 연결할 필요 없이 하나의 엔드포인트에서 모든 컴포넌트 정보를 받습니다.

덕분에 디자인 시스템의 기본 컴포넌트와 제품의 도메인 컴포넌트를 모두 파악한 상태에서 코드를 생성하죠. “디자인 시스템의 Button을 쓸 건지, 제품에서 확장한 PrimaryButton을 쓸 건지”를 상황에 맞게 판단하게 됩니다.

Chromatic으로 원격 퍼블리싱

로컬 개발 서버에서만 MCP를 쓸 수 있으면 CI/CD나 팀 협업에서는 쓰기 어렵겠죠. Chromatic은 Storybook MCP 서버를 원격으로 퍼블리싱하는 기능을 바로 지원해요.

Chromatic에 Storybook을 배포하면 MCP 서버도 함께 호스팅되는데, 품질 검사, 버전 관리, 인증이 모두 포함되어 있습니다. 팀의 모든 개발자가 동일한 MCP 서버에 접속해서 같은 컴포넌트 맥락을 공유하게 됩니다.

로컬에서 Storybook을 띄우지 않아도 되니까 코드 리뷰나 PR 작성 시에도 에이전트가 최신 컴포넌트 정보를 기반으로 제안해줍니다. 코드 품질을 팀 전체에서 맞추기 수월해지죠.

Skills와의 차이

Storybook 쪽에서는 MCP 외에도 Skills라는 방식으로 에이전트에게 컴포넌트 정보를 전달하는 접근법도 함께 개발하고 있습니다. Skills는 에이전트에게 특정 작업을 수행하는 방법을 가르치는 문서 기반의 방식인데요. “이 디자인 시스템의 버튼을 쓸 때는 이렇게 import하고 이런 props를 넘기세요” 같은 지침을 텍스트로 제공하는 거예요.

Skills도 유용하지만 MCP와는 역할이 다릅니다. Skills는 정적인 지침서라면 MCP는 양방향 통신 채널입니다. 에이전트가 Storybook에 “이 컴포넌트의 최신 props 목록을 알려줘”라고 요청하고 응답을 받는 식의 실시간 상호작용은 MCP여야 가능하거든요. 특히 자동 테스트를 돌리고 결과를 받아서 코드를 수정하는 자체 검증 루프는 MCP의 양방향 통신 없이는 구현할 수 없습니다.

현재 제한 사항

Storybook MCP는 아직 초기 단계라서 몇 가지 제한이 있습니다.

가장 큰 건 현재 React 프로젝트만 지원한다는 점이에요. Vue, Angular, Svelte 같은 다른 프레임워크는 2026년 후반에 지원될 예정입니다. React를 쓰고 있지 않다면 아직은 기다려야 하는데, Storybook이 원래 다양한 프레임워크를 지원하는 도구인 만큼 시간 문제일 거예요.

Storybook 10.3 이상이 필요하다는 점도 있습니다. 기존에 Storybook을 쓰고 있다면 업그레이드가 선행되어야 하는데, 메이저 버전 업그레이드인 만큼 마이그레이션 작업이 필요할 수 있어요.

라이브 프리뷰 같은 일부 기능은 AI 클라이언트 쪽에서 MCP Apps를 지원해야 동작하는데, 아직 모든 AI 도구가 이걸 지원하지는 않아서 사용하는 도구에 따라 경험이 달라집니다.

마치며

AI 에이전트에게 UI를 맡기려면 “어떤 컴포넌트가 있고 어떻게 쓰는지”를 알려줘야 합니다. Storybook MCP는 이미 Storybook에 잘 정리해둔 컴포넌트 문서와 스토리를 MCP 프로토콜로 에이전트에게 전달해서 이 문제를 깔끔하게 풀고 있어요.

컴포넌트 재사용률이 올라가고 코드 생성이 빨라지는 것도 좋지만 진짜 핵심은 에이전트가 우리 디자인 시스템에 맞는 코드를 작성하게 된다는 점입니다. 라이브 프리뷰와 자동 테스트까지 갖추고 나면 에이전트가 만든 코드를 사람이 일일이 검수하는 부담도 줄어들겠죠.

React 프로젝트에서 Storybook을 이미 쓰고 있다면 MCP 애드온 하나 추가하는 것만으로 에이전트의 코드 품질이 확 달라지는 걸 경험할 수 있을 겁니다.

더 자세한 내용은 Storybook MCP 공식 블로그 포스트를 참고하세요.