Skip to content
Back to search

shadcn-ui-mcp-server

A mcp server to allow LLMS gain context about shadcn ui component structure,usage and installation,compaitable with react,svelte 5,vue & React Native

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jpisnice--shadcn-ui-mcp-server/badge.svg)](/listings/jpisnice--shadcn-ui-mcp-server)

HTML

<a href="/listings/jpisnice--shadcn-ui-mcp-server"><img src="/api/listings/jpisnice--shadcn-ui-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Basic usage (60 requests/hour)
npx @jpisnice/shadcn-ui-mcp-server

# With GitHub token (5000 requests/hour) - Recommended
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here

# Switch frameworks
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

# Use Base UI instead of Radix (React only)
npx @jpisnice/shadcn-ui-mcp-server --ui-library base

**🎯 Get your GitHub token in 2 minutes**: [docs/getting-started/github-token.md](docs/getting-started/github-token.md)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 306 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Shadcn UI v4 MCP Server
  2. [![npm version](https://badge.fury.io/js/@jpisnice%2Fshadcn-ui-mcp-server.svg)](https://badge.fury.io/js/@jpisnice%2Fshadcn-ui-mcp-server)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![MCP spec 2026-07-28](https://img.shields.io/badge/MCP_spec-2026--07--28-blue)](https://modelcontextprotocol.io/specification/2026-07-28)
  5. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/Jpisnice/shadcn-ui-mcp-server)](https://archestra.ai/mcp-catalog/jpisnice__shadcn-ui-mcp-server)
  6. > **πŸš€ The fastest way to integrate shadcn/ui components into your AI workflow**
  7. A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to [shadcn/ui v4](https://ui.shadcn.com/) components, blocks, demos, and metadata. Seamlessly retrieve React, Svelte, Vue, and React Native implementations for your AI-powered development workflow.
  8. ## ✨ Key Features
  9. - **🎯 Multi-Framework Support** - React, Svelte, Vue, and React Native implementations
  10. - **πŸ“¦ Component Source Code** - Latest shadcn/ui v4 TypeScript source
  11. - **🎨 Component Demos** - Example implementations and usage patterns
  12. - **πŸ—οΈ Blocks Support** - Complete block implementations (dashboards, calendars, forms)
  13. - **πŸ“‹ Metadata Access** - Dependencies, descriptions, and configuration details
  14. - **πŸ” Directory Browsing** - Explore repository structures
  15. - **⚑ Smart Caching** - Efficient GitHub API integration with rate limit handling, plus protocol cache hints (`ttlMs`/`cacheScope`) on list and read results
  16. - **⌨️ Argument Completion** - Autocomplete for prompt and resource-template arguments (component names, package managers, build tools, and more)
  17. - **🌐 Streamable HTTP Transport** - Stateless `/mcp` endpoint for multi-client deployments (MCP spec 2026-07-28)
  18. - **🐳 Docker Ready** - Production-ready containerization with Docker Compose
  19. ## πŸš€ Quick Start
  20. ```bash
  21. # Basic usage (60 requests/hour)
  22. npx @jpisnice/shadcn-ui-mcp-server
  23. # With GitHub token (5000 requests/hour) - Recommended
  24. npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here
  25. # Switch frameworks
  26. npx @jpisnice/shadcn-ui-mcp-server --framework svelte
  27. npx @jpisnice/shadcn-ui-mcp-server --framework vue
  28. npx @jpisnice/shadcn-ui-mcp-server --framework react-native
  29. # Use Base UI instead of Radix (React only)
  30. npx @jpisnice/shadcn-ui-mcp-server --ui-library base
  31. ```
  32. **🎯 Get your GitHub token in 2 minutes**: [docs/getting-started/github-token.md](docs/getting-started/github-token.md)
  33. ## πŸ“¦ One-Click Installation (Claude Desktop)
  34. Download and double-click the `.mcpb` file for instant installation:
  35. 1. Download `shadcn-ui-mcp-server.mcpb` from [Releases](https://github.com/Jpisnice/shadcn-ui-mcp-server/releases)
  36. 2. Double-click the file - Claude Desktop opens automatically
  37. 3. Enter your GitHub token (optional, for higher rate limits)
  38. 4. Click Install - tools are available immediately
  39. **Manual install:** Claude Desktop β†’ Settings β†’ MCP β†’ Add Server β†’ Browse β†’ Select `.mcpb` file
  40. > **References:** [Anthropic Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions) | [Building MCPB](https://support.claude.com/en/articles/12922929-building-desktop-extensions-with-mcpb)
  41. ## 🌐 HTTP Transport & Docker Deployment
  42. The server implements the **2026-07-28 MCP specification** (via MCP TypeScript SDK v2) and stays compatible with 2025-era clients. To make your client use the modern protocol, or to require it, see the [Modern Protocol Guide](docs/getting-started/modern-protocol.md). Besides stdio, it can serve **Streamable HTTP** at a single stateless `/mcp` endpoint for multi-client and production deployments:
  43. ### Quick Start with HTTP
  44. ```bash
  45. # HTTP mode (stateless, supports many concurrent clients)
  46. node build/index.js --mode http --port 7423
  47. # Docker Compose (production ready)
  48. docker-compose up -d
  49. # Connect with Claude Code
  50. claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp
  51. ```
  52. ### Transport Modes
  53. - **`stdio`** (default) - Standard input/output for CLI usage
  54. - **`http`** - Streamable HTTP at `/mcp`
  55. - **`dual`** - Both stdio and HTTP simultaneously
  56. > The legacy SSE transport (`/sse` + `/message`) was removed. `--mode sse` is still accepted as a deprecated alias for `http`.
  57. ### Docker Examples
  58. ```bash
  59. # Basic container
  60. docker run -p 7423:7423 shadcn-ui-mcp-server
  61. # With GitHub API token
  62. docker run -p 7423:7423 -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token shadcn-ui-mcp-server
  63. # Docker Compose (recommended)
  64. docker-compose up -d
  65. curl http://localhost:7423/health
  66. ```
  67. ### Environment Variables
  68. - `MCP_TRANSPORT_MODE` - Transport mode (stdio|http|dual)
  69. - `MCP_PORT` - HTTP server port (default: 7423 - SHADCN on keypad!)
  70. - `MCP_HOST` - Host binding (default: 0.0.0.0)
  71. - `MCP_CORS_ORIGINS` - CORS origins (comma-separated)
  72. - `MCP_PROTOCOL` - Protocol eras to accept: `any` (default; 2026-07-28 plus 2025-era fallback) or `modern` (2026-07-28 only). CLI: `--protocol`
  73. - `GITHUB_PERSONAL_ACCESS_TOKEN` - GitHub API token
  74. - `UI_LIBRARY` - UI primitive library: `radix` (default) or `base` (React only)
  75. ## πŸ“š Documentation
  76. | Section | Description |
  77. |---------|-------------|
  78. | [πŸš€ Getting Started](docs/getting-started/) | Installation, setup, and first steps |
  79. | [βš™οΈ Configuration](docs/configuration/) | Framework selection, tokens, and options |
  80. | [πŸ”Œ Integration](docs/integration/) | Editor and tool integrations |
  81. | [πŸ“– Usage](docs/usage/) | Examples, tutorials, and use cases |
  82. | [🎨 Frameworks](docs/frameworks/) | Framework-specific documentation |
  83. | [πŸ› Troubleshooting](docs/troubleshooting/) | Common issues and solutions |
  84. | [πŸ”§ API Reference](docs/api/) | Tool reference and technical details |
  85. ## 🎨 Framework Support
  86. This MCP server supports four popular shadcn implementations:
  87. | Framework | Repository | Maintainer | Description |
  88. |-----------|------------|------------|-------------|
  89. | **React** (default) | [shadcn/ui](https://ui.shadcn.com/) | [shadcn](https://github.com/shadcn) | React components from shadcn/ui v4 |
  90. | **Svelte** | [shadcn-svelte](https://www.shadcn-svelte.com/) | [huntabyte](https://github.com/huntabyte) | Svelte components from shadcn-svelte |
  91. | **Vue** | [shadcn-vue](https://www.shadcn-vue.com/) | [unovue](https://github.com/unovue) | Vue components from shadcn-vue |
  92. | **React Native** | [react-native-reusables](https://github.com/founded-labs/react-native-reusables) | [Founded Labs](https://github.com/founded-labs) | React Native components from react-native-reusables |
  93. ### UI Library (React only)
  94. shadcn/ui v4 supports two primitive libraries for React: **Radix UI** (default) and **Base UI**.
  95. ```bash
  96. # Radix UI (default)
  97. npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library radix
  98. # Base UI
  99. npx @jpisnice/shadcn-ui-mcp-server --framework react --ui-library base
  100. # Or via environment variable
  101. UI_LIBRARY=base npx @jpisnice/shadcn-ui-mcp-server
  102. ```
  103. Claude Desktop config example:
  104. ```json
  105. {
  106. "args": ["--framework", "react", "--ui-library", "base"]
  107. }
  108. ```
  109. ## πŸ› οΈ Essential Setup
  110. ### 1. Get GitHub Token (Recommended)
  111. ```bash
  112. # Visit: https://github.com/settings/tokens
  113. # Generate token with no scopes needed
  114. export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
  115. ```
  116. ### 2. Run Server
  117. ```bash
  118. # React (default)
  119. npx @jpisnice/shadcn-ui-mcp-server
  120. # Svelte
  121. npx @jpisnice/shadcn-ui-mcp-server --framework svelte
  122. # Vue
  123. npx @jpisnice/shadcn-ui-mcp-server --framework vue
  124. # React Native
  125. npx @jpisnice/shadcn-ui-mcp-server --framework react-native
  126. ```
  127. ### 3. Integrate with Your Editor
  128. - **Autohand Code**: See [Autohand Code Integration](#-autohand-code-integration) below
  129. - **Claude Code**: See [Claude Code Integration](#-claude-code-integration) below
  130. - **VS Code**: [docs/integration/vscode.md](docs/integration/vscode.md)
  131. - **Cursor**: [docs/integration/cursor.md](docs/integration/cursor.md)
  132. - **Claude Desktop**: [docs/integration/claude-desktop.md](docs/integration/claude-desktop.md)
  133. - **Continue.dev**: [docs/integration/continue.md](docs/integration/continue.md)
  134. ## πŸ’» Autohand Code Integration
  135. Use the [Autohand Code CLI](https://github.com/autohandai/code-cli/) to add the shadcn/ui MCP server:
  136. ```bash
  137. autohand mcp add shadcn bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN
  138. ```
  139. Add `--scope project` before `shadcn` to save the server in the current project's `.autohand` configuration instead of your user configuration.
  140. ## πŸ’» Claude Code Integration
  141. ### Quick Add (CLI)
  142. ```bash
  143. # Add the shadcn-ui MCP server
  144. claude mcp add shadcn -- bunx -y @jpisnice/shadcn-ui-mcp-server --github-api-key YOUR_TOKEN
  145. ```
  146. ### HTTP Transport
  147. For production deployments with the Streamable HTTP transport:
  148. ```bash
  149. # Start server in HTTP mode
  150. node build/index.js --mode http --port 7423
  151. # Connect with Claude Code
  152. claude mcp add --scope user --transport http shadcn-mcp-server http://localhost:7423/mcp
  153. ```
  154. ### Framework-Specific Commands
  155. See [Claude Code Integration Guide](docs/integration/claude-code.md) for framework-specific commands (React, Svelte, Vue, React Native).
  156. > **Reference:** [Claude Code MCP Documentation](https://code.claude.com/docs/en/mcp)
  157. ## 🎯 Use Cases
  158. - **AI-Powered Development** - Let AI assistants build UIs with shadcn/ui
  159. - **Multi-Client Deployments** - Stateless HTTP transport scales horizontally without sticky sessions
  160. - **Production Environments** - Docker Compose ready with health checks and monitoring
  161. - **Component Discovery** - Explore available components and their usage
  162. - **Multi-Framework Learning** - Compare React, Svelte, Vue, and React Native implementations
  163. - **Rapid Prototyping** - Get complete block implementations for dashboards, forms, etc.
  164. - **Code Generation** - Generate component code with proper dependencies
  165. ## πŸ“¦ Installation
  166. ```bash
  167. # Global installation (optional)
  168. npm install -g @jpisnice/shadcn-ui-mcp-server
  169. # Or use npx (recommended)
  170. npx @jpisnice/shadcn-ui-mcp-server
  171. ```
  172. ## πŸ”¨ Building from Source
  173. ### Prerequisites
  174. - Node.js >= 20.0.0
  175. - npm or pnpm
  176. ### Build Steps
  177. ```bash
  178. # Clone the repository
  179. git clone https://github.com/Jpisnice/shadcn-ui-mcp-server.git
  180. cd shadcn-ui-mcp-server
  181. # Install dependencies
  182. npm install
  183. # Build the project
  184. npm run build
  185. # Run the server
  186. node build/index.js --github-api-key YOUR_TOKEN
  187. ```
  188. ### Run Locally
  189. ```bash
  190. # After building, run with options
  191. node build/index.js --github-api-key YOUR_TOKEN
  192. node build/index.js --framework svelte
  193. ```
  194. ### Building MCPB Package
  195. The project includes a `manifest.json` following the [MCPB specification](https://github.com/modelcontextprotocol/mcpb). The `.mcpb` file is a ZIP archive containing the server, dependencies, and configuration.
  196. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed packaging instructions.
  197. > **Reference:** [Building Desktop Extensions with MCPB](https://support.claude.com/en/articles/12922929-building-desktop-extensions-with-mcpb)
  198. ## πŸ”— Quick Links
  199. - πŸ“– [Full Documentation](docs/)
  200. - πŸš€ [Getting Started Guide](docs/getting-started/)
  201. - 🌐 [HTTP Transport & Docker Guide](HTTP_TRANSPORT.md)
  202. - 🧭 [Modern Protocol Guide (2026-07-28)](docs/getting-started/modern-protocol.md)
  203. - πŸ“ [Changelog](CHANGELOG.md)
  204. - 🎨 [Framework Comparison](docs/frameworks/)
  205. - πŸ”§ [API Reference](docs/api/)
  206. - πŸ› [Troubleshooting](docs/troubleshooting/)
  207. - πŸ’¬ [Issues & Discussions](https://github.com/Jpisnice/shadcn-ui-mcp-server)
  208. ## πŸ“„ License
  209. MIT License - see [LICENSE](LICENSE) for details.
  210. ## πŸ™ Acknowledgments
  211. - **[shadcn](https://github.com/shadcn)** - For the amazing React UI component library
  212. - **[huntabyte](https://github.com/huntabyte)** - For the excellent Svelte implementation
  213. - **[unovue](https://github.com/unovue)** - For the comprehensive Vue implementation
  214. - **[Founded Labs](https://github.com/founded-labs)** - For the React Native implementation
  215. - **[Anthropic](https://anthropic.com)** - For the Model Context Protocol specification
  216. ---
  217. **Made with ❀️ by [Janardhan Polle](https://github.com/Jpisnice)**
  218. **Star ⭐ this repo if you find it helpful!**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.