Serwer MCP shadcn/ui

Serwer MCP shadcn to serwer stdio wbudowany w CLI shadcn (npx shadcn@latest mcp). Daje Claude Code, Codeksowi i Cursorowi siedem narzędzi do wyszukiwania i podglądu komponentów oraz generowania poleceń instalacji z rejestru shadcn i z każdego prywatnego rejestru wpisanego w components.json. Serwer tylko czyta; pliki nadal zapisuje polecenie shadcn add.

Prosisz agenta o okno potwierdzenia usunięcia. Dostajesz 80 linii ręcznie pisanego modala z własną pułapką fokusu, choć components/ui/alert-dialog.tsx jest o jedno shadcn add stąd albo już leży w repozytorium. Z dostępem do rejestru agent sprawdza, co istnieje, instaluje prawdziwy komponent i go składa, więc UI zostaje przy jednym design systemie.

Ta strona jest dla programistów, którzy budują interfejsy React z shadcn/ui i agentem, oraz dla tech leadów, którzy odpowiadają za components.json i firmowy rejestr.

Co zyskasz dzięki serwerowi MCP shadcn

• Serwer zainstalowany w Claude Code, Codeksie i Cursorze przez shadcn mcp init oraz ręczny wpis dla Codeksa, którego CLI za ciebie nie zapisze.
• Decyzję: serwer MCP, skill shadcn czy oba.
• Trzy prompty do skopiowania: znajdź i zainstaluj komponenty, zbuduj z nich funkcję, pobierz je z prywatnego rejestru.
• Bramkę weryfikacji (dry run, sprawdzenie typów, linter, testy i zrzut ekranu), która dowodzi poprawności bez czytania wygenerowanych komponentów.
• Pułapki powtarzane przez starsze poradniki i pamięć modeli, sprawdzone na shadcn 4.21.0.

Serwer MCP, skill shadcn czy oba?

shadcn udostępnia dwie integracje dla agentów i pokrywają się one bardziej, niż sugerują nazwy. Skill shadcn (z repozytorium shadcn-ui/ui) uczy agenta obsługi samego CLI: zaczyna od npx shadcn@latest info --json, czyta dokumentację komponentów przez npx shadcn@latest docs <component> i sprawdza istniejące komponenty, zanim napisze własne UI. Serwer MCP wystawia rejestr jako ustrukturyzowane narzędzia, które agent wywołuje bezpośrednio.

Potrzeba	Wybierz	Dlaczego
Dodawanie, poprawianie i stylowanie komponentów w jednym projekcie	skill	Do momentu uruchomienia kosztuje około 100 tokenów opisu i najpierw czyta konfigurację projektu
Wyszukiwanie w kilku rejestrach z przestrzeniami nazw (@shadcn, @acme)	serwer MCP	Wyszukiwanie rozmyte i podgląd elementów we wszystkich rejestrach z components.json
Wdrożenie zespołowe, w którym każdy klient ma działać tak samo	oba	Skill daje metodę pracy, serwer daje wyszukiwanie w rejestrze
Migracja projektu z Radix UI na Base UI	skill migrate-radix-to-base	Jest w tym samym repozytorium i migruje pojedynczy komponent albo cały projekt

Skill zainstalujesz przez CLI skills (lista sprawdzona we wrześniu 2026 na skills 1.7.0; repozytorium zawiera shadcn i migrate-radix-to-base):

# Terminal, katalog główny projektu. --skill ogranicza instalację do jednego skilla.
npx skills add shadcn/ui --skill shadcn

Skill shadcn/improve to coś innego o podobnej nazwie: przepływ audytu i planowania zmian w kodzie, opisany na osobnej stronie. O instalowaniu, aktualizowaniu i zakresach skilli ogólnie przeczytasz w przewodniku Instalowanie i zarządzanie skillami.

Zainstaluj serwer MCP shadcn w Claude Code, Codeksie i Cursorze

Wpis serwera jest w każdym kliencie taki sam: npx shadcn@latest mcp. Różni się tylko to, kto zapisuje plik konfiguracji. Polecenie mcp init --client przyjmuje claude, cursor, vscode, codex i opencode (sprawdzone w shadcn mcp init --help, 4.21.0).

1. Zainicjuj shadcn/ui w projekcie, jeśli nie ma jeszcze components.json. Narzędzia rejestru czytają z tego pliku listę rejestrów.

   npx shadcn@latest init

2. Zarejestruj serwer w swoim kliencie.

   Claude Code

   # Zapisuje wpis "shadcn" w .mcp.json w katalogu głównym projektu
   npx shadcn@latest mcp init --client claude

   Albo zarejestruj go własnym poleceniem Claude Code, współdzielonym z zespołem przez .mcp.json:

   claude mcp add --scope project shadcn -- npx shadcn@latest mcp

   Uruchom /mcp w sesji, żeby potwierdzić połączenie, i zatwierdź serwer projektu, gdy Claude Code o to zapyta.

   Codex

   mcp init --client codex nie edytuje konfiguracji Codeksa; wypisuje blok do dodania i kończy pracę. Dodaj go sam do ~/.codex/config.toml:

   [mcp_servers.shadcn]
   command = "npx"
   args = ["shadcn@latest", "mcp"]

   Albo pozwól Codeksowi zapisać ten sam wpis:

   codex mcp add shadcn -- npx shadcn@latest mcp
   codex mcp list   # shadcn powinien być na liście

   Uruchom Codeksa ponownie, żeby załadował serwer.

   Cursor

   # Zapisuje wpis "shadcn" w .cursor/mcp.json w katalogu głównym projektu
   npx shadcn@latest mcp init --client cursor

   Wynikowy plik:

   {
     "mcpServers": {
       "shadcn": {
         "command": "npx",
         "args": ["shadcn@latest", "mcp"]
       }
     }
   }

   Jeśli serwer jest wyłączony, włącz go w ustawieniach MCP Cursora.

3. Sprawdź efekt uboczny. W teście z września 2026 na shadcn 4.21.0 mcp init dodał też shadcn do devDependencies i utworzył plik blokady zależności, gdy go nie było. Zacommituj tę zmianę świadomie albo ją cofnij.

Przy każdym starcie serwera npx pobiera wersję wskazaną przez tag @latest. Żeby cały zespół pracował na jednej wersji, przypnij ją w argumentach ("shadcn@4.21.0") i podbijaj w zwykłym pull requeście.

Co robi siedem narzędzi serwera MCP shadcn

Listę narzędzi odczytano z odpowiedzi tools/list serwera (shadcn 4.21.0, wrzesień 2026). Starsze poradniki wymieniają sześć i pomijają get_project_registries.

Narzędzie	Co zwraca
get_project_registries	Nazwy rejestrów skonfigurowanych w components.json; gdy pliku brak, pusta lista (bez błędu), wbrew opisowi narzędzia
list_items_in_registries	Elementy z jednego lub kilku rejestrów, z filtrem po typie
search_items_in_registries	Wyszukiwanie rozmyte po nazwach i opisach elementów
view_items_in_registries	Nazwę, opis, typ i zawartość plików elementu
get_item_examples_from_registries	Kod przykładów, np. accordion-demo, z zależnościami
get_add_command_for_items	Dokładne polecenie shadcn add dla wybranych elementów
get_audit_checklist	Stałą, sześciopunktową listę: importy, remotePatterns dla next/image, zależności, linter, TypeScript i „użyj Playwright MCP, jeśli jest dostępny”

Lista audytowa to statyczny tekst, a nie skaner. Przypomina agentowi, co sprawdzić; nie zagląda do twoich plików.

Znajdź, zainstaluj i złóż komponenty z agentem

W praktyce sprawdza się kolejność: wyszukaj, obejrzyj przykłady, zrób podgląd instalacji, zainstaluj, a potem złóż i zweryfikuj. Poniższe prompty kodują tę kolejność, żeby agent nie pominął podglądu.

Prompt do skopiowania: znajdź i zainstaluj właściwe komponenty

Use the shadcn MCP server. I need a confirmation step before deleting a project and a toast after it succeeds.
1. Check components/ui/ for anything already installed that fits.
2. Search the registry for the missing pieces and show me the examples for each candidate.
3. Get the add command, run it with --dry-run first and list the files it would create or overwrite.
4. Stop and wait for my go-ahead before running it for real.

Agent powinien wywołać search_items_in_registries, potem get_item_examples_from_registries i get_add_command_for_items, a na koniec wypisać listę plików z --dry-run i się zatrzymać. Jeśli pisze komponent bez tych wywołań, zignorował serwer.

Prompt do skopiowania: formularz ustawień z komponentów rejestru

Use the shadcn MCP server to view the examples for form, input, select, switch and button, then build src/components/settings-form.tsx:
- fields: name (required), email (valid email), timezone (select), weekly digest (switch)
- validation with the same form library and schema pattern the form example uses
- only components from components/ui/; no hand-written modal, input or toggle
When done, call get_audit_checklist, then run the type check, the linter and the tests, and report each result. Do not report done while any of them fails.

Ostatnia linia ma znaczenie: dzięki niej lista audytowa staje się poleceniami z kodami wyjścia, a nie listą odhaczaną przez agenta z pamięci.

Pobieraj komponenty z prywatnego rejestru firmy

Tech lead może opublikować wewnętrzne komponenty jako rejestr z przestrzenią nazw i podpiąć go do każdego projektu. Dodaj go przez CLI albo bezpośrednio w components.json:

npx shadcn@latest registry add @acme=https://registry.acme.dev/r/{name}.json

{
  "registries": {
    "@acme": {
      "url": "https://registry.acme.dev/r/{name}.json",
      "headers": { "Authorization": "Bearer ${ACME_REGISTRY_TOKEN}" }
    }
  }
}

URL musi zawierać symbol zastępczy {name}, a CLI odczytuje ${ACME_REGISTRY_TOKEN} ze zmiennych środowiskowych, więc token nigdy nie trafia do pliku. Zamień @acme i adres na swój rejestr.

Prompt do skopiowania: najpierw rejestr firmowy

Call get_project_registries. For the billing page, search @acme first and use its components wherever one fits; fall back to @shadcn only for pieces @acme does not have, and list which registry each component came from. Show the add commands with --dry-run before installing anything.

Jak udowodnić, że komponenty działają, bez czytania każdej linii

Komponent z rejestru to kod dołączony do repozytorium: shadcn add kopiuje go do projektu i od tej chwili to ty go testujesz. Poniższa bramka pozwala recenzentowi przyjąć zmianę na podstawie dowodów.

1. Podgląd przed zapisem. npx shadcn@latest add alert-dialog --dry-run pokazuje, co się zmieni; --diff pokazuje, czym lokalny plik różni się od wersji z rejestru. Nieoczekiwane nadpisanie dostosowanego komponentu zatrzymasz tutaj.
2. Kontrole maszynowe. Sprawdzenie typów, linter i testy jednostkowe muszą przejść w CI, nie tylko w podsumowaniu agenta.
3. Kontrola zachowania. Test Playwright albo weryfikacja w przeglądarce prowadzona przez agenta otwiera stronę, wywołuje okno i robi zrzut ekranu. Lista zwracana przez serwer prosi o ten sam krok.
4. Kontrola zakresu. git diff --stat powinien pokazać nowe pliki w components/ui/ i plik z nową funkcjonalnością, nic więcej. Zmiany w globals.css, tailwind.config.* lub components.json wymagają w pull requeście nazwanego powodu.

Recenzent czyta plik z nową funkcjonalnością i dowody, a nie skopiowane do repozytorium komponenty bazowe. Tech lead odpowiedzialny za components.json zatwierdza nowe rejestry i podbicia przypiętej wersji CLI.

Ile kontekstu kosztuje serwer MCP shadcn

Siedem definicji narzędzi zajęło w tools/list około 4,7 KB schematu JSON (shadcn 4.21.0, wrzesień 2026), czyli mniej więcej 1200 tokenów przy czterech znakach na token. To niewiele w porównaniu z dużymi serwerami dostawców, ale płaci się to w każdej sesji. view_items_in_registries zwraca pełną zawartość plików, więc podgląd pięciu komponentów naraz może kosztować znacznie więcej niż schemat. Proś o przykłady jednego komponentu naraz, a filtrowanie narzędzi opisuje strona Jak ograniczyć koszt tokenów MCP. W Claude Code uruchom /context przed włączeniem serwera i po nim, żeby zobaczyć koszt we własnej sesji.

Jak popularny jest shadcn/ui?

Repozytorium shadcn-ui/ui, w którym są CLI, serwer MCP i skille, miało 124,6 tys. gwiazdek na GitHubie 2026-09-26 (odczyt z GitHuba w dossier ekosystemu z września 2026). Gwiazdki mierzą cały projekt, a nie użycie serwera MCP; liczby instalacji samego serwera nie udało się ustalić.

Które instrukcje dla serwera MCP shadcn są błędne lub nieaktualne?

Pułapki ze starszych poradników i pamięci modeli (sprawdzone na shadcn 4.21.0, wrzesień 2026)

• „mcp init --client codex konfiguruje Codeksa”. Tylko wypisuje blok TOML. Dodaj [mcp_servers.shadcn] sam albo użyj codex mcp add.
• npx shadcn diff. Polecenie jest przestarzałe; używaj npx shadcn@latest add <component> --diff.
• npx shadcn-ui …. shadcn-ui to stara nazwa pakietu; npm oznacza go jako przestarzały. Pakiet nazywa się shadcn.
• „Sześć narzędzi”. Jest siedem; starsze listy pomijają get_project_registries.
• „Lista audytowa skanuje twoje komponenty”. Zwraca stały tekst i niczego nie sprawdza.
• Porty dla Svelte, Vue i React Native jako wbudowane rejestry tego serwera. Serwer działa z @shadcn i rejestrami z twojego components.json. Porty społecznościowe mają własne CLI; sprawdź dokumentację portu, zanim założysz, że serwer go zainstaluje.

Gdy serwer MCP shadcn przestaje działać

Narzędzia kończą się błędem pobierania rejestru. Dla rejestru @shadcn serwer pobiera dane z ui.shadcn.com, a proxy lub zapora, która go blokuje, psuje każde wyszukiwanie. Sprawdź w tej samej powłoce npx shadcn@latest search @shadcn -q dialog; jeśli to też zawodzi, odblokuj host albo ustaw proxy dla klienta. Więcej w problemach z połączeniem MCP.

get_project_registries nie wymienia żadnych rejestrów. W katalogu, w którym wystartował serwer, nie ma components.json. Narzędzie kończy się sukcesem z pustą listą; wyszukiwanie w @shadcn nadal działa, ale każda inna przestrzeń nazw, np. @acme, kończy się błędem Unknown registry. Uruchom npx shadcn@latest init albo startuj klienta z katalogu głównego projektu, żeby serwer miał właściwy katalog roboczy.

„Unknown registry @acme”. Przestrzeni nazw nie ma w sekcji registries pliku components.json. Dodaj ją przez shadcn registry add i uruchom klienta ponownie, żeby serwer wczytał plik od nowa.

Prywatny rejestr zwraca 401. Zmienna z tokenem nie jest ustawiona w środowisku, które dziedziczy serwer MCP. Wyeksportuj ją przed startem klienta albo przekaż przez ustawienie env serwera MCP w kliencie; nie wklejaj tokenu do components.json.

Agent nadpisał dostosowany komponent. Uruchomił add z --overwrite albo zatwierdził pytanie. Przywróć plik z gita i zostaw linię „najpierw dry run, czekaj na moją zgodę” w promptach albo w CLAUDE.md / AGENTS.md.

Agent nadal pisze własne UI. Serwer jest podłączony, ale agent go nie wywołuje. Nazwij serwer w prompcie („use the shadcn MCP server”) albo zainstaluj skill shadcn, którego instrukcje każą agentowi szukać istniejących komponentów przed pisaniem nowych.

Co dalej z shadcn i agentami

Figma MCP: od projektu do kodu Zmapuj ramkę z Figmy na komponenty shadcn i udowodnij, że implementacja się z nią zgadza.

Najlepsze skille do frontendu Skille frontendowe warte instalacji obok skilla shadcn.

Playwright MCP Daj agentowi przeglądarkę, żeby sprawdził zainstalowane komponenty.

Przegląd serwerów MCP Gdzie serwer shadcn mieści się wśród serwerów potrzebnych zespołowi.