shadcn-ui-mcp-server

Shadcn UI v4 MCP 서버

🚀 shadcn/ui 컴포넌트를 AI 워크플로에 통합하는 가장 빠른 방법

AI 어시스턴트가 shadcn/ui v4 컴포넌트, 블록, 데모, 메타데이터에 포괄적으로 접근할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다. AI 기반 개발 워크플로를 위해 React, Svelte, Vue, React Native 구현을 손쉽게 가져오세요.

✨ 주요 기능

🎯 멀티 프레임워크 지원 - React, Svelte, Vue, React Native 구현
📦 컴포넌트 소스 코드 - 최신 shadcn/ui v4 TypeScript 소스
🎨 컴포넌트 데모 - 예제 구현 및 사용 패턴
🏗️ 블록 지원 - 완전한 블록 구현 (대시보드, 캘린더, 폼)
📋 메타데이터 접근 - 의존성, 설명, 구성 세부 정보
🔍 디렉터리 탐색 - 저장소 구조 탐색
⚡ 스마트 캐싱 - 속도 제한 처리를 포함한 효율적인 GitHub API 통합, 그리고 목록 및 읽기 결과에 대한 프로토콜 캐시 힌트(ttlMs / cacheScope)
⌨️ 인자 자동 완성 - 프롬프트 및 리소스 템플릿 인자(컴포넌트 이름, 패키지 매니저, 빌드 도구 등)에 대한 자동 완성
🌐 Streamable HTTP 전송 - 다중 클라이언트 배포를 위한 상태 비저장 /mcp 엔드포인트 (MCP 스펙 2026-07-28)
🐳 Docker 지원 - Docker Compose를 통한 프로덕션 준비 컨테이너화

🚀 빠른 시작
# 기본 사용법 (시간당 60회 요청)
npx @jpisnice/shadcn-ui-mcp-server

# GitHub 토큰 사용 (시간당 5000회 요청) - 권장
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# 프레임워크 전환
npx @jpisnice/shadcn-ui-mcp-server --framework svelte
npx @jpisnice/shadcn-ui-mcp-server --framework vue
npx @jpisnice/shadcn-ui-mcp-server --framework react-native

# Radix 대신 Base UI 사용 (React 전용)
npx @jpisnice/shadcn-ui-mcp-server --ui-library base
🎯 2분 만에 GitHub 토큰 발급받기 : docs/getting-started/github-token.md

📦 원클릭 설치 (Claude Desktop)
.mcpb 파일을 다운로드하고 더블클릭하면 즉시 설치됩니다:

Releases에서 shadcn-ui-mcp-server.mcpb 다운로드
파일 더블클릭 - Claude Desktop이 자동으로 열립니다
GitHub 토큰 입력 (선택 사항, 더 높은 속도 제한용)
Install 클릭 - 도구를 즉시 사용할 수 있습니다

수동 설치: Claude Desktop → Settings → MCP → Add Server → Browse → .mcpb 파일 선택

참고: Anthropic Desktop Extensions | Building MCPB

🌐 HTTP 전송 및 Docker 배포
이 서버는 2026-07-28 MCP 스펙(MCP TypeScript SDK v2 경유)을 구현하며 2025년대 클라이언트와 호환됩니다. 클라이언트가 최신 프로토콜을 사용하도록 하거나 이를 요구하려면 Modern Protocol Guide를 참조하세요. stdio 외에도 다중 클라이언트 및 프로덕션 배포를 위해 단일 상태 비저장 /mcp 엔드포인트에서 Streamable HTTP를 제공할 수 있습니다:

HTTP로 빠른 시작
# HTTP 모드 (상태 비저장, 다수 동시 클라이언트 지원)
node build/index.js --mode http --port 7423

# Docker Compose (프로덕션 준비 완료)
docker-compose up -d

# Claude Code로 연결
claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp
전송 모드

stdio (기본값) - CLI 사용을 위한 표준 입출력
http - /mcp에서 Streamable HTTP
dual - stdio와 HTTP 동시 사용

레거시 SSE 전송(/sse + /message)은 제거되었습니다. --mode sse는 여전히 http의 사용 중단된 별칭으로 허용됩니다.

Docker 예제
# 기본 컨테이너
docker run -p 7423:7423 shadcn-ui-mcp-server

# GitHub API 토큰 사용
docker run -p 7423:7423 -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token shadcn-ui-mcp-server

# Docker Compose (권장)
docker-compose up -d
curl http://localhost:7423/health
환경 변수

MCP_TRANSPORT_MODE - 전송 모드 (stdio|http|dual)
MCP_PORT - HTTP 서버 포트 (기본값: 7423 - 키패드의 SHADCN!)
MCP_HOST - 호스트 바인딩 (기본값: 0.0.0.0)
MCP_CORS_ORIGINS - CORS 오리진 (쉼표로 구분)
MCP_PROTOCOL - 허용할 프로토콜 시대: any (기본값; 2026-07-28 및 2025년대 폴백) 또는 modern (2026-07-28만). CLI: --protocol
GITHUB_PERSONAL_ACCESS_TOKEN - GitHub API 토큰
UI_LIBRARY - UI 프리미티브 라이브러리: radix (기본값) 또는 base (React 전용)

📚 문서

섹션
설명

🚀 시작하기
설치, 설정 및 첫 단계

⚙️ 구성
프레임워크 선택, 토큰 및 옵션

🔌 통합
에디터 및 도구 통합

📖 사용법
예제, 튜토리얼 및 사용 사례

🎨 프레임워크
프레임워크별 문서

🐛 문제 해결
일반적인 문제 및 해결 방법

🔧 API 참조
도구 참조 및 기술 세부 정보

🎨 프레임워크 지원
이 MCP 서버는 네 가지 인기 있는 shadcn 구현을 지원합니다:

프레임워크
저장소
관리자
설명

React (기본값)
shadcn/ui
shadcn
shadcn/ui v4의 React 컴포넌트

Svelte
shadcn-svelte
huntabyte
shadcn-svelte의 Svelte 컴포넌트

Vue
shadcn-vue
unovue
shadcn-vue의 Vue 컴포넌트

React Native
react-native-reusables
Founded Labs
react-native-reusables의 React Native 컴포넌트

UI 라이브러리 (React 전용)
shadcn/ui v4는 React용 두 가지 프리미티브 라이브러리를 지원합니다: Radix UI (기본값) 및 Base UI.

# Radix UI (기본값)
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library radix

# Base UI
npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library base

# 또는 환경 변수 사용
UI_LIBRARY=base npx @jpisnice/shadcn-ui-mcp-server
Claude Desktop 구성 예시:

{
"args" : [ " --framework " , " react " , " --ui-library " , " base " ]
}
🛠️ 필수 설정
1. GitHub 토큰 발급 (권장)
# 방문: https://github.com/settings/tokens
# 스코프 없이 토큰 생성
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
2. 서버 실행
# React (기본값)
npx @jpisnice/shadcn-ui-mcp-server

# Svelte
npx @jpisnice/shadcn-ui-mcp-server --framework svelte

# Vue
npx @jpisnice/shadcn-ui-mcp-server --framework vue

# React Native
npx @jpisnice/shadcn-ui-mcp-server --framework react-native
3. 에디터와 통합

Autohand Code : 아래 Autohand Code 통합 참조
Claude Code : 아래 Claude Code 통합 참조
VS Code : docs/integration/vscode.md
Cursor : docs/integration/cursor.md
Claude Desktop : docs/integration/claude-desktop.md
Continue.dev : docs/integration/continue.md

💻 Autohand Code 통합
Autohand Code CLI를 사용하여 shadcn/ui MCP 서버를 추가하세요:

autohand mcp add shadcn bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN
사용자 구성 대신 현재 프로젝트의 .autohand 구성에 서버를 저장하려면 shadcn 앞에 --scope project를 추가하세요.

💻 Claude Code 통합
빠른 추가 (CLI)
# shadcn-ui MCP 서버 추가
claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN
HTTP 전송
Streamable HTTP 전송을 사용한 프로덕션 배포:

# HTTP 모드로 서버 시작
node build/index.js --mode http --port 7423

# Claude Code로 연결
claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp
프레임워크별 명령어
프레임워크별 명령어(React, Svelte, Vue, React Native)는 Claude Code Integration Guide를 참조하세요.

참고: Claude Code MCP Documentation

🎯 사용 사례

AI 기반 개발 - AI 어시스턴트가 shadcn/ui로 UI를 구축하도록 지원
다중 클라이언트 배포 - 상태 비저장 HTTP 전송은 스티키 세션 없이 수평 확장
프로덕션 환경 - 상태 확인 및 모니터링이 포함된 Docker Compose 준비 완료
컴포넌트 탐색 - 사용 가능한 컴포넌트 및 사용법 탐색
멀티 프레임워크 학습 - React, Svelte, Vue, React Native 구현 비교
신속한 프로토타이핑 - 대시보드, 폼 등에 대한 완전한 블록 구현 확보
코드 생성 - 적절한 의존성을 갖춘 컴포넌트 코드 생성

📦 설치
# 전역 설치 (선택 사항)
npm install -g @jpisnice/shadcn-ui-mcp-server

# 또는 npx 사용 (권장)
npx @jpisnice/shadcn-ui-mcp-server
🔨 소스에서 빌드
사전 요구 사항

Node.js >= 20.0.0
npm 또는 pnpm

빌드 단계
# 저장소 복제
git clone https://github.com/Jpisnice/shadcn-ui-mcp-server.git
cd shadcn-ui-mcp-server

# 의존성 설치
npm install

# 프로젝트 빌드
npm run build

# 서버 실행
node build/index.js --github-api-key YOUR_TOKEN
로컬 실행
# 빌드 후 옵션과 함께 실행
node build/index.js --github-api-key YOUR_TOKEN
node build/index.js --framework svelte
MCPB 패키지 빌드
이 프로젝트는 MCPB 스펙을 따르는 manifest.json을 포함합니다. .mcpb 파일은 서버, 의존성, 구성을 포함하는 ZIP 아카이브입니다.

자세한 패키징 지침은 CONTRIBUTING.md를 참조하세요.

참고: Building Desktop Extensions with MCPB

🔗 빠른 링크

📖 전체 문서
🚀 시작하기 가이드
🌐 HTTP 전송 및 Docker 가이드
🧭 Modern Protocol 가이드 (2026-07-28)
📝 변경 로그
🎨 프레임워크 비교
🔧 API 참조
🐛 문제 해결
💬 이슈 및 토론

📄 라이선스
MIT 라이선스 - 자세한 내용은 LICENSE 참조.

🙏 감사의 말

shadcn - 놀라운 React UI 컴포넌트 라이브러리 제공
huntabyte - 훌륭한 Svelte 구현 제공
unovue - 포괄적인 Vue 구현 제공
Founded Labs - React Native 구현 제공
Anthropic - Model Context Protocol 스펙 제공

Made with ❤️ by Janardhan Polle

도움이 되었다면 이 저장소에 ⭐를 눌러주세요!