Stitch MCP 실전 가이드 — 설치부터 UI 생성까지

Google Stitch는 텍스트 프롬프트로 UI 디자인과 프론트엔드 코드를 만들어주는 도구입니다. Stitch MCP는 이걸 AI 코딩 에이전트(Claude Code, Cursor, Gemini CLI 등)에서 직접 쓸 수 있게 연결해주는 MCP 서버입니다.

공식 문서가 있긴 한데, 설치 순서만 나열돼 있고 실전에서 어떻게 쓰는지는 빠져 있습니다. 이 글은 설치부터 실제 UI 생성까지 한 번에 정리합니다.

Stitch MCP가 뭔데

Stitch는 Google Labs에서 만든 실험적 도구입니다. Gemini 2.5 Pro 기반으로, 프롬프트를 입력하면 UI 디자인 + HTML/CSS 코드를 생성합니다.

Stitch MCP는 이 Stitch API를 MCP(Model Context Protocol) 서버로 감싸서, AI 에이전트가 도구(tool)로 호출할 수 있게 만든 겁니다.

즉: 에이전트한테 "랜딩 페이지 만들어줘"라고 하면, 에이전트가 Stitch를 호출해서 디자인 + 코드를 가져옵니다.

지원 플랫폼

플랫폼에 관계없이 MCP 서버 설정 방식은 거의 동일합니다.

설치

사전 준비

• Node.js 18+
• Google Cloud 프로젝트 (빌링 활성화)
• stitch.withgoogle.com에서 프로젝트 하나 이상 생성

자동 설정 (권장)

npx @_davideast/stitch-mcp init

대화형 위저드가 뜹니다. gcloud CLI 확인/설치, Google 로그인, 프로젝트 설정, Stitch API 활성화, MCP 클라이언트 설정까지 한 번에 처리합니다.

수동 설정 (gcloud 직접)

이미 gcloud가 설치돼 있으면:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default login
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
gcloud beta services mcp enable stitch.googleapis.com --project=YOUR_PROJECT_ID

상태 확인

npx @_davideast/stitch-mcp doctor --verbose

문제가 있으면 여기서 잡힙니다.

플랫폼별 MCP 등록

Claude Code

claude mcp add -e GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID -s user stitch -- npx -y @_davideast/stitch-mcp proxy

확인:

claude mcp list | grep stitch

Claude Desktop

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["@_davideast/stitch-mcp", "proxy"]
    }
  }
}

Cursor / VS Code / Windsurf

MCP 설정에 동일한 JSON 추가:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["-y", "@_davideast/stitch-mcp", "proxy"]
    }
  }
}

Gemini CLI

gemini mcp add stitch -- npx -y @_davideast/stitch-mcp proxy --env GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

또는 확장으로 설치:

gemini extensions install https://github.com/gemini-cli-extensions/stitch --auto-update

이미 gcloud가 설정돼 있으면 환경변수 하나 추가:

{
  "env": {
    "STITCH_USE_SYSTEM_GCLOUD": "1"
  }
}

사용 가능한 도구(Tools)

에이전트가 호출할 수 있는 주요 도구입니다.

실전: 이렇게 씁니다

1. 프롬프트 하나로 UI 생성

에이전트에게:

Stitch에서 다크 모드 대시보드를 만들어줘.
카드 기반 레이아웃으로, 상단에 통계 요약, 하단에 차트.

에이전트가 generate_screen_from_text를 호출해서 UI를 생성하고, get_screen_code로 HTML/CSS를 가져옵니다.

실제로 Stitch에 프롬프트를 넣으면 이런 결과가 나옵니다:

모바일 앱도 마찬가지입니다. 프롬프트 하나로 피트니스 트래커를 만들면:

프롬프트만 잘 쓰면 꽤 완성도 높은 UI가 나옵니다. 여기서 나온 HTML/CSS를 그대로 프로젝트에 가져가거나, 디자인 레퍼런스로 쓸 수 있습니다.

2. 여러 화면을 한 번에

한 프로젝트에서 여러 화면을 만들 수 있습니다. 예를 들어 피트니스 앱이라면:

3. 디자인 DNA로 일관성 유지

여러 화면을 만들 때 문제가 있습니다. 화면마다 스타일이 달라요. Stitch가 이전 화면을 기억하지 않기 때문입니다.

해결법:

기존 대시보드 스크린에서 디자인 DNA를 추출해줘.
그 스타일로 설정 페이지를 새로 만들어줘.

extract_design_context가 색상 팔레트, 타이포그래피, 레이아웃 패턴을 추출하고, 새 스크린 생성 시 컨텍스트로 넘깁니다.

3. Astro 사이트 자동 생성

CLI에서 직접:

# 스크린 미리보기
npx @_davideast/stitch-mcp serve -p PROJECT_ID

# Astro 프로젝트 생성
npx @_davideast/stitch-mcp site -p PROJECT_ID

스크린을 라우트에 매핑하면 Astro 사이트가 자동으로 만들어집니다.

4. 대화형 브라우저

npx @_davideast/stitch-mcp view --projects

터미널에서 프로젝트와 스크린을 탐색할 수 있습니다. c로 복사, s로 HTML 미리보기, o로 Stitch에서 열기.

자주 겪는 문제

API Key로 인증하면 안 됩니다

가장 흔한 실수입니다. STITCH_API_KEY 환경변수를 넣으면:

Error: "API keys are not supported by this API.
Expected OAuth2 access token or other authentication credentials."

MCP 프록시는 OAuth가 필요합니다. gcloud auth application-default login으로 인증하세요.

.env 파일 충돌

프로젝트 디렉토리에 .env 파일이 있으면 프록시가 깨질 수 있습니다. invalid character 'd' 에러가 나면 .env를 다른 데로 옮기거나 이름을 바꾸세요.

권한 에러

Google Cloud 프로젝트에서:

• 빌링 활성화 확인
• Stitch API 활성화 확인 (gcloud beta services mcp enable stitch.googleapis.com)
• 계정 권한 확인 (Owner 또는 Editor)

완전 초기화

뭔가 꼬였으면:

npx @_davideast/stitch-mcp logout --force --clear-config
npx @_davideast/stitch-mcp init

팁

• 프롬프트는 구체적으로. "좋게 만들어줘"보다 "다크 모드, 카드 기반, 미니멀"이 훨씬 나은 결과를 줍니다
• 모바일 UI가 웹보다 품질이 높은 편입니다
• 프리뷰 기간이라 현재 무료입니다
• 프로덕션에서는 버전을 고정하세요: @_davideast/stitch-mcp@0.0.5
• MCP 구현이 3가지 있는데, @_davideast/stitch-mcp가 가장 안정적입니다

마무리

Stitch MCP는 "에이전트한테 UI 만들어달라고 하면 진짜 만들어지는" 도구입니다.

설치는 npx @_davideast/stitch-mcp init 하나면 되고, 어떤 AI 코딩 도구든 MCP 설정만 추가하면 바로 연결됩니다. 디자인 도구를 따로 열 필요 없이 에이전트한테 말하면 됩니다.

참고: Stitch 공식 사이트 · stitch-mcp GitHub · MCP 셋업 문서 · MCP 가이드