Design Review MCP

디자인 작업물을 AI가 자동으로 검토해주는 Claude Code 확장 도구입니다. 웹 페이지 스크린샷을 찍고, AI가 디자인 피드백을 주고, 반영 여부를 결정하면 기록까지 남겨줍니다.

이런 분들을 위한 도구입니다

• 혼자 또는 소규모 팀에서 디자인 작업을 하면서 객관적인 디자인 검토가 필요한 분
• 여러 화면의 디자인 일관성을 빠르게 확인하고 싶은 분
• 디자인 리뷰 히스토리를 체계적으로 기록하고 싶은 분
• Claude Code를 사용하면서 디자인 품질 관리를 자동화하고 싶은 분

할 수 있는 것들

스크린샷 자동 캡처

웹 페이지 주소를 알려주면 자동으로 스크린샷을 찍어줍니다. 특정 요소가 로딩될 때까지 기다리거나, 버튼 클릭 같은 동작을 한 뒤 캡처하는 것도 가능합니다.

AI 디자인 분석

스크린샷을 AI(Gemini)가 분석해서 타이포그래피, 색상, 간격, 접근성 등에 대한 피드백을 줍니다. 이전에 이미 검토한 내용은 자동으로 참고해서 같은 지적이 반복되지 않습니다.

여러 화면 비교 분석

여러 화면의 스크린샷을 한 번에 보내서, 화면 간 타이포그래피·색상·컴포넌트가 일관적인지 검토합니다.

피드백 검토 & 수정 지시서 생성

AI가 준 디자인 피드백 중 반영할 것과 넘길 것을 결정하면, 반영할 항목을 자동으로 수정 지시서로 만들어줍니다.

리뷰 기록 저장

어떤 피드백을 반영했고, 어떤 것을 넘겼는지를 근거와 함께 기록 파일로 남깁니다.

리뷰 기록 조회

지금까지의 디자인 리뷰 기록을 한눈에 볼 수 있습니다. 어떤 유형의 피드백을 주로 반영하거나 넘기는지 패턴도 요약해 줍니다.

반응형 멀티 뷰포트 캡처

하나의 URL을 모바일(375px), 태블릿(768px), 데스크톱(1440px) 등 여러 화면 크기로 한 번에 캡처합니다. 반응형 디자인이 각 디바이스에서 어떻게 보이는지 빠르게 확인할 수 있습니다.

Before/After 비교 분석

수정 전후 스크린샷을 AI가 비교 분석합니다. 이전에 받았던 피드백을 함께 전달하면, 각 피드백이 제대로 반영되었는지 자동으로 검증해 줍니다.

디자인 리뷰 리포트

지금까지 쌓인 디자인 리뷰 기록을 분석하여 반영률, 자주 넘기는 패턴, 가장 많이 리뷰된 화면 등을 정리한 리포트를 만들어 줍니다.

접근성 검사

웹 페이지의 접근성을 WCAG 기준으로 자동 검사합니다. 명도 대비, 대체 텍스트, 키보드 접근성 등 위반 사항을 검출하고 구체적인 수정 방법을 안내합니다.

시작하기

1단계: Gemini API 키 발급

AI 디자인 분석을 위해 Google Gemini API 키가 필요합니다 (무료).

1. Google AI Studio에 접속합니다
2. Google 계정으로 로그인합니다
3. "API 키 만들기" 버튼을 클릭합니다
4. 생성된 키를 복사해 둡니다

2단계: Claude Code에 등록

터미널에 아래 한 줄을 붙여넣으세요. 여기에-API-키-붙여넣기 부분만 1단계에서 복사한 키로 바꿔주면 됩니다.

claude mcp add design-review-mcp \
  -e GEMINI_API_KEY=여기에-API-키-붙여넣기 \
  -- npx -y design-review-mcp

끝입니다! 처음 실행할 때 스크린샷 촬영에 필요한 브라우저가 자동으로 설치됩니다.

사용 방법

기본 워크플로우

Claude Code에서 자연스럽게 대화하듯 사용하면 됩니다:

1. 스크린샷 찍기 — "이 페이지 스크린샷 찍어줘" 라고 하면 자동으로 캡처합니다
2. 디자인 분석 — "이 스크린샷 디자인 분석해줘" 라고 하면 AI가 피드백을 줍니다
3. 피드백 검토 — AI가 준 피드백을 보고, 반영할 것과 넘길 것을 결정합니다
4. 기록 저장 — 결정 내용이 기록 파일로 저장됩니다
5. 다음 리뷰 — 같은 화면을 다시 분석하면, 이전에 넘긴 피드백은 다시 나오지 않습니다

여러 화면 비교하기

1. 비교할 화면들의 스크린샷을 여러 장 찍습니다
2. "이 화면들 디자인 일관성 비교해줘" 라고 하면 한 번에 분석합니다
3. 화면 간 불일치 사항을 확인하고, 반영 여부를 결정합니다

실제 사용 예시 (Claude Code 대화)

나: localhost:3000/onboarding 페이지 스크린샷 찍어줘

Claude: 스크린샷을 캡처했습니다. /tmp/screenshots/onboarding.png에 저장되었습니다.

나: 이 스크린샷 디자인 분석해줘. 브랜드 가이드라인은 ./brand-guide.md에 있어

Claude: AI 디자인 분석 결과입니다:
  1. [타이포그래피] 본문 텍스트 행간이 1.2로 좁습니다 (권장: 1.5~1.6)
  2. [색상] CTA 버튼과 배경의 명도 대비가 3.8:1로 WCAG AA 기준(4.5:1) 미달
  3. [간격] 카드 간 간격이 불균일합니다 (12px, 16px, 12px)

나: 1번, 2번은 반영하고 3번은 넘길게. 간격은 의도한 거야.

Claude: 수정 지시서를 만들었습니다:
  - 본문 텍스트 행간을 1.5로 수정
  - CTA 버튼 색상을 명도 대비 4.5:1 이상으로 조정
  결정 내용을 기록 파일에 저장했습니다.

리뷰 기록은 어디에 저장되나요?

프로젝트 폴더 안에 design-logs 폴더가 자동으로 만들어지고, 그 안에 기록이 쌓입니다.

design-logs/
├── onboarding-step-1/          ← 화면별 폴더
│   ├── 2025-06-15.md           ← 날짜별 기록 파일
│   └── 2025-06-16.md
└── _cross-screen/              ← 여러 화면 비교 기록
    └── onboarding-flow/
        └── 2025-06-15.md

각 기록 파일에는 AI 피드백 내용, 반영/넘기기 결정과 이유, 수정 지시서가 담겨 있습니다.

자주 묻는 질문

Q: Gemini API 키는 유료인가요? A: 기본 사용량은 무료입니다. 일반적인 디자인 리뷰 용도로는 무료 범위 안에서 충분히 사용할 수 있습니다.

Q: 어떤 종류의 디자인 피드백을 받을 수 있나요? A: 타이포그래피(글꼴, 크기, 행간), 색상(대비, 일관성), 간격(여백, 정렬), 접근성(WCAG 기준), 컴포넌트 일관성 등을 검토합니다.

Q: 브랜드 가이드라인 문서는 어떤 형식이어야 하나요? A: Markdown, 텍스트 파일 등 텍스트로 읽을 수 있는 형식이면 됩니다. 색상 코드, 폰트 규칙, 간격 기준 등을 적어두면 AI가 이를 참고해서 더 정확한 피드백을 줍니다.

Q: 이전에 넘긴 피드백이 다시 나오나요? A: 아니요. 같은 화면을 다시 분석할 때, 이전에 넘기기로 한 피드백은 자동으로 제외됩니다.

Q: 로컬 개발 서버가 아닌 배포된 사이트도 분석할 수 있나요? A: 네, 접근 가능한 URL이면 모두 분석할 수 있습니다.

로컬 개발

git clone https://github.com/your-username/design-review-mcp.git
cd design-review-mcp
npm install
npx playwright install chromium
npm run build

로컬에서 빌드한 서버를 직접 등록하려면:

claude mcp add design-review-mcp \
  -e GEMINI_API_KEY=your-key \
  -- node /절대경로/dist/server.js

npm 배포

npm login
npm publish

배포 후 사용자는 npx -y design-review-mcp로 바로 실행할 수 있습니다.

프로젝트 구조

design-review-mcp/
├── src/
│   ├── server.ts                    # MCP 서버 엔트리
│   ├── types.ts                     # TypeScript 인터페이스
│   ├── config/
│   │   └── config-manager.ts        # API 키 및 설정 관리
│   ├── providers/
│   │   ├── vision-provider.ts       # Vision API 추상 인터페이스
│   │   └── gemini-provider.ts       # Gemini 구현체
│   ├── prompts/
│   │   ├── single-screen-prompt.ts  # 단일 화면 분석 프롬프트
│   │   ├── cross-screen-prompt.ts   # 여러 화면 비교 프롬프트
│   │   └── compare-versions-prompt.ts # Before/After 비교 프롬프트
│   ├── logs/
│   │   ├── log-formatter.ts         # Markdown 렌더링
│   │   ├── log-writer.ts            # 로그 파일 쓰기
│   │   └── log-reader.ts            # 로그 파일 읽기 및 패턴 분석
│   └── tools/
│       ├── capture-screenshot.ts    # 스크린샷 캡처
│       ├── capture-responsive.ts    # 반응형 멀티 뷰포트 캡처
│       ├── analyze-screenshot.ts    # AI 디자인 분석
│       ├── compare-versions.ts      # Before/After 비교 분석
│       ├── cross-screen-review.ts   # 여러 화면 비교
│       ├── review-feedback.ts       # 피드백 검토 및 수정 지시서
│       ├── log-changes.ts           # 기록 저장
│       ├── get-change-history.ts    # 기록 조회
│       ├── generate-report.ts       # 디자인 리뷰 리포트
│       └── audit-accessibility.ts   # 접근성 검사
└── dist/
    └── server.js                    # 빌드 결과물

기술 스택

| 항목 | 선택 | |------|------| | MCP Framework | @modelcontextprotocol/sdk | | 스크린샷 | playwright (headless Chromium) | | Vision API | Google Gemini (@google/generative-ai) | | 로그 저장 | Local Markdown files | | 스키마 검증 | zod | | 빌드 | tsup (ESM) |

라이선스

MIT