# Jpisnice/shadcn-ui-mcp-server: shadcn/ui components inside your AI assistant

> An MCP server that serves shadcn/ui v4 source, demos, blocks and metadata to AI assistants across React, Svelte, Vue and React Native. It installs through npx or a Claude Desktop extension, and its main constraint is the GitHub API rate limit.

**Jpisnice/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

- Repository: https://github.com/Jpisnice/shadcn-ui-mcp-server
- Stars: 3,008 · Forks: 310
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/jpisnice-shadcn-ui-mcp-server

## The gap this server fills for shadcn/ui projects

shadcn/ui is not a dependency you install and import. The components live in your repository as source files you own, and the canonical copies live in upstream repositories. An AI assistant asked to add a dialog or a data table therefore has two bad options: reproduce the component from training data, which drifts from the current v4 output, or ask you to paste the file. The README frames the project as a way to give assistants "comprehensive access to shadcn/ui v4 components, blocks, demos, and metadata," and that is the honest description of the problem. The server does not generate UI. It retrieves the upstream implementation so the model works from the real thing.

The intended user is a frontend engineer already committed to shadcn/ui who drives an MCP-capable assistant. The multi-framework design matters more than it first appears: shadcn-svelte, shadcn-vue and react-native-reusables are separate projects with separate maintainers, and the server switches between their repositories rather than assuming React. If your stack is plain React with Radix primitives, you are on the default path and the least configuration is required.

## How the server retrieves component source over MCP

The mechanism is a TypeScript process that exposes MCP tools and answers them by reading from GitHub. The README lists the capabilities as component source code, demos, blocks, metadata, and directory browsing, plus smart caching with rate limit handling. So a request for a component resolves to a GitHub API call against the repository for the selected framework, and the response is returned to the assistant as tool output. The caching layer exists because the same component is often requested repeatedly within one session.

Framework selection is a startup concern, not a per-request one. The default is React; the Svelte, Vue and React Native implementations come from the repositories named in the README table (shadcn/ui, shadcn-svelte, shadcn-vue, react-native-reusables). For React there is a second axis: the primitive library can be Radix, the default, or Base UI. That is a v4 distinction, and it is set with the same flag or environment variable used for the framework. Nothing in the README suggests the server inspects your project to guess either value, so both are yours to state correctly.

Transport is the third moving part. The default stdio mode suits a single editor client. SSE mode, documented in SSE_IMPLEMENTATION.md and wired up in the Dockerfile and docker-compose.yml, supports multiple concurrent connections over HTTP. Dual mode runs both at once. The port default is 7423, which the README notes is SHADCN on a phone keypad.

## Installing shadcn-ui-mcp-server and making a first request

The quickest path is npx, which needs no local checkout. Run it bare and you get the React components with the unauthenticated GitHub rate limit of 60 requests per hour:

```bash
npx @jpisnice/shadcn-ui-mcp-server
```

The process starts and waits on stdio for an MCP client. Running it in a terminal by hand will look like nothing happened, which is expected: there is no interactive prompt.

For real work, pass a GitHub token. The README states that no scopes are needed, and the ceiling rises to 5000 requests per hour:

```bash
npx @jpisnice/shadcn-ui-mcp-server --github-api-key ghp_your_token_here
```

If your project is not React, add the framework flag. The README gives these exact forms:

```bash
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
```

React projects on Base UI primitives instead of Radix add a second flag, and the README shows the equivalent Claude Desktop configuration using an args array:

```json
{
  "args": ["--framework", "react", "--ui-library", "base"]
}
```

Claude Desktop also has a one-click route: download shadcn-ui-mcp-server.mcpb from Releases and double-click it. The README describes the flow as Claude Desktop opening automatically, a prompt for the optional GitHub token, and an Install button, after which the tools are available. The manual equivalent is Settings, then MCP, then Add Server, then Browse to the .mcpb file.

For a shared or containerised deployment, the repository ships a Dockerfile and a compose file that set MCP_TRANSPORT_MODE=sse, MCP_HOST=0.0.0.0 and MCP_PORT=7423, and mount a logs volume. The README's connection example for Claude Code is:

```bash
claude mcp add --scope user --transport sse shadcn-mcp-server http://localhost:7423/sse
```

After the container is up, the documented health check is a curl against the health endpoint on the same port. Note that the compose file's healthcheck stanza points curl at port 3001 while the container, the Dockerfile's own HEALTHCHECK and the published port mapping all use 7423. Treat that stanza as inconsistent with the rest of the file rather than as documentation of a second port.

## Rate limits, token handling and the wrong-tool cases

The binding constraint is GitHub. Without a token you are capped at 60 requests per hour, and a single exploratory session that pulls a component, its demo and its block metadata can consume several. The README is explicit that the token raises the limit to 5000, and it recommends that path. The caching layer reduces repeat traffic but cannot help a genuinely broad sweep across many components.

Token handling deserves attention on the Docker route. The compose file passes GITHUB_PERSONAL_ACCESS_TOKEN through from the host environment with an empty default, so an unset variable starts the server unauthenticated without failing loudly. You find out when requests start being rejected. The README does not document rollback, version pinning or a migration path between releases, so pinning the npx invocation to a specific published version is a decision you make on your own rather than one the project describes.

This is also the wrong tool in several common situations. If your components are not shadcn/ui, the server has nothing relevant to return; it is a retrieval layer for four specific upstream repositories, not a general component search engine. If you have already vendored and customised your components, the upstream v4 source may differ from what is in your tree, and the assistant will be reading the wrong file. If your editor has no MCP client, there is no integration path. And if your goal is generating new component designs rather than pulling existing ones, this adds a network hop without adding capability.

## How it differs from the shadcn CLI and from pasting source

The closest alternative in most workflows is the shadcn CLI itself. The CLI writes files into your project: you run it, it resolves the registry entry and places the component in your components directory. The MCP server never writes to your project. It returns source and metadata as tool output so the assistant can read and reason about them before deciding what to generate. The difference is who acts. With the CLI, you act and the assistant sees the result afterwards. With the MCP server, the assistant acts with the upstream source in context.

That distinction has a practical consequence. The CLI is authoritative about what lands on disk and handles registry resolution for you. The MCP server is authoritative about what the model knows while it writes, which is exactly the part that goes wrong when a model reconstructs a component from memory. For a team that wants the assistant to add a component correctly on the first attempt, the two are complementary rather than competing: the server informs the edit, the CLI or the assistant's own file write produces it.

The other alternative is manual context. Pasting component source into the chat works and requires no installation, but it is per-file, per-session and depends on you knowing which files matter. The server removes that step at the cost of a running process, a token, and a network dependency on GitHub's API.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-05-16. The release history shows v1.0.1 in June 2025, v1.1.4 in October 2025, and v2.0.0 in January 2026, which is a cadence of a few releases a year rather than continuous churn. The v2.0.0 release is the one that aligns with shadcn/ui v4 and the Base UI option, so a project on v1 is not merely behind on patches.

Upgrade cost is mostly configuration rather than code, because you do not import this package into your application. What changes between releases is the flag set, the environment variable names and the transport behaviour. The published surface is a bin entry named shadcn-mcp pointing at build/index.js, so a pinned npx version or a pinned container tag is the practical way to control when a change reaches your team. The npm scripts show a prepublishOnly chain that runs a security audit, a licence check and Snyk before clean and build, which indicates the maintainer intends published artifacts to pass those gates. The secret scanning script is a placeholder that echoes a message rather than running a scanner.

The licence is MIT, which permits commercial use and modification. That is the whole of the licence implication here; whether MIT satisfies your organisation's policy on bundled dependencies is a question for your own review, and the repository's licence-checker script reports the summary for the dependency tree rather than for this package alone.

## Conclusion

Adopt it if your team already writes shadcn/ui components and you want the assistant to read real v4 source instead of reconstructing it from memory, especially on a React or Next.js codebase where the default framework setting matches. Skip it if you are not on shadcn/ui, if your editor has no MCP client, or if you cannot supply a GitHub token and expect heavy use, because the unauthenticated ceiling is 60 requests per hour. Before rolling it out, verify three things: that the framework flag matches your actual component library, that the token is present in the environment the server reads, and that your client reaches the health endpoint on port 7423 if you take the Docker route.

## FAQ

### Does shadcn have an MCP?

shadcn/ui itself is a component distribution rather than an MCP provider. This project is a third-party MCP server, published as @jpisnice/shadcn-ui-mcp-server, that serves shadcn/ui v4 source, demos, blocks and metadata to AI assistants.

### How do I set up Shadcn MCP?

Run it with npx, either bare or with a GitHub token for the higher rate limit, or install the .mcpb file in Claude Desktop by double-clicking it and entering a token when prompted. Then point your MCP client at the server, using the SSE command shown in the README if you deployed it with Docker.

### How to get access to MCP server?

For this server there is no account or approval step. It runs locally through npx or as a container, and the only credential mentioned is a GitHub personal access token with no scopes required, which raises the API limit from 60 to 5000 requests per hour.

### What are some free MCP servers available?

This one is free to run and MIT licensed, and it works without a GitHub token at 60 requests per hour. The README recommends supplying a token anyway, since the unauthenticated limit is easy to exhaust when browsing components, demos and blocks.

## Sources

- [Issues](https://github.com/Jpisnice/shadcn-ui-mcp-server/issues)
- [Jpisnice/shadcn-ui-mcp-server on GitHub](https://github.com/Jpisnice/shadcn-ui-mcp-server)
- [License: MIT](https://github.com/Jpisnice/shadcn-ui-mcp-server/blob/master/LICENSE)
- [README](https://github.com/Jpisnice/shadcn-ui-mcp-server/blob/master/README.md)
- [Releases](https://github.com/Jpisnice/shadcn-ui-mcp-server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jpisnice-shadcn-ui-mcp-server