Cursor shadcn Setup: MCP-Server, .mdc-Regeln, Registries

Agent, der KI-Agent in Cursor, schreibt shadcn/ui-Code aus dem Gedächtnis, solange du ihm nichts Besseres gibst. Er greift zur Button-API aus seinem Training, übersieht die Registry, die du letzte Woche in components.json eingetragen hast, und setzt bg-blue-500, wo dein Theme ein Token hat. Ein Cursor shadcn Setup, auf das du dich verlassen kannst, besteht aus vier Teilen: dem shadcn-MCP-Server, damit Agent echte Registries durchsuchen kann, einer Projektregel, die sagt, wie er das Gefundene nutzt, der Registry-Liste in components.json und einer CLI, die die Dateien schreibt. Dieses Tutorial richtet alle vier ein, ergänzt eine zweite Registry neben shadcn/ui und endet mit Prompts und einem fertigen Admin-Screen aus Data Table, Dialog und Button.

Alle Befehle unten haben wir am 16. Oktober 2026 ausgeführt, mit shadcn 4.22.0, der skills-CLI 1.7.2 und unserer eigenen Registry, Wingo UI 1.9.0 (CLI 1.0.3). Was wir über Cursor schreiben, stammt aus den MCP-Docs (opens in a new tab), den Rules-Docs (opens in a new tab) und den Skills-Docs (opens in a new tab) von Cursor, Stand desselben Tages. Ob Agent mit Composer oder einem anderen Modell läuft, ändert daran nichts. Den Überblick über KI-Agenten und Komponentenbibliotheken liefert unser Guide zu MCP für Komponentenbibliotheken.

Was braucht ein Cursor shadcn Setup?

Einen Server, eine Regeldatei, eine Registry-Liste und eine CLI pro Registry:

Ein eigener MCP-Server der Bibliothek ist optional. Er lohnt sich, wenn die Bibliothek Props und Designregeln veröffentlicht, denn die liefert der shadcn-Server nicht mit.

Wie füge ich den shadcn-MCP-Server zu Cursor hinzu?

Führ im Stammordner des Projekts einen einzigen Befehl aus:

npx shadcn@latest mcp init --client cursor

Er hat Configuration saved to .cursor/mcp.json. ausgegeben, shadcn zu den devDependencies hinzugefügt und diese Datei geschrieben:

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

So lässt sich Cursor MCP einrichten, und zwar auf Projektebene: Committe .cursor/mcp.json, und das ganze Team bekommt den Server. Dasselbe Format in ~/.cursor/mcp.json gilt für jedes Projekt auf deinem Rechner. Einen neuen Server musst du in Cursor trotzdem erst über seinen Schalter aktivieren, bevor Agent ihn sieht; Stand Oktober 2026 liegen die Schalter laut den Docs von Cursor unter Customize in der Seitenleiste. Sobald die Verbindung steht, erscheinen seine Tools unter Available Tools, und Agent ruft sie auf, wenn ein Prompt sie braucht.

Welche Tools bringt der shadcn-MCP-Server in Cursor mit?

Sieben, und alle nur lesend. Diese Liste hat der Server gemeldet, sobald die Cursor shadcn MCP-Verbindung stand:

• get_project_registries: die Registries in components.json.
• list_items_in_registries und search_items_in_registries: durchblättern oder unscharf suchen, mit Paging.
• view_items_in_registries: Name, Beschreibung, Typ, Anzahl der Dateien und npm-Abhängigkeiten.
• get_item_examples_from_registries: Demo-Code, gefunden über Namen wie dialog-demo.
• get_add_command_for_items: der npx shadcn@latest add-Befehl für eine Liste von Items.
• get_audit_checklist: eine kurze Checkliste, die du nach dem Generieren von Code abarbeitest.

Daraus folgen drei Dinge. Der Server schreibt nie eine Datei: Jede Installation ist ein Terminal-Befehl, der deinem Run-Modus folgt, und standardmäßig fragt Cursor nach, bevor es ein MCP-Tool nutzt. Du kannst die Argumente jedes Aufrufs also vorher lesen. Der Server schickt keine Anweisungen mit, also sagt Agent niemand, dass er vor dem Schreiben von UI suchen soll; das ist Aufgabe der Regel. Und view_items_in_registries hat für @shadcn/button und unseren Dialog keine Props geliefert, Agent lernt eine API also aus der installierten Datei oder aus der Doku der Bibliothek.

Wie füge ich eine zweite Registry hinzu?

Trag sie unter registries in components.json ein. Eine öffentliche Registry braucht nur eine URL-Vorlage:

{
  "registries": {
    "@wingo-ui": "https://wingo-ui.com/r/{name}.json"
  }
}

Eine private Registry bekommt ein Objekt mit URL und Headern, das Secret steht in einer Umgebungsvariable:

{
  "registries": {
    "@wingo-ui": {
      "url": "https://wingo-ui.com/r/{name}.json",
      "headers": { "Authorization": "Bearer ${WINGO_UI_API_KEY}" }
    }
  }
}

Die shadcn-CLI setzt ${VAR} aus deiner Umgebung oder aus .env.local ein (danach .env.development.local, .env.development und .env), der Key landet also nie in components.json.

Mit der einfachen URL deckt eine Suche beide Registries ab. Das ist die echte Antwort von search_items_in_registries auf „data table“ über @shadcn und @wingo-ui mit einem Limit von 5, gekürzt auf die ersten drei Treffer:

Found 182 items matching "data table" in registries @shadcn, @wingo-ui:

Showing items 1-5 of 182:

- data-table (registry:ui) - The admin table on TanStack Table v9: search, filters, sorting, bulk actions, pinning, resizing, virtualization and cards on phones. [@wingo-ui]
  Add command: `npx shadcn@latest add @wingo-ui/data-table`
- data-table-demo (registry:example) [@shadcn]
  Add command: `npx shadcn@latest add @shadcn/data-table-demo`
- dashboard-01 (registry:block) - A dashboard with sidebar, charts and data table. [@shadcn]
  Add command: `npx shadcn@latest add @shadcn/dashboard-01`

Die 182 Treffer kommen von der unscharfen Suche, setz also ein kleines Limit. Kostenpflichtige Items scheitern mit einem klaren Fehler: Ohne Key hat view_items_in_registries für unsere Data Table einen 402 geliefert (Data Table is part of Wingo UI Pro) und im selben Aufruf auch nichts für @shadcn/button. Frag kostenpflichtige und kostenlose Items deshalb getrennt ab.

Was passiert, wenn beide Registries components/ui/button.tsx schreiben?

Irgendetwas geht so oder so kaputt. Viele Bibliotheken im shadcn-Stil installieren nach components/ui, mit denselben Dateinamen und anderen APIs. Die Varianten unseres Buttons sind solid, soft, outline, ghost und link, und destruktiv heißt bei uns tone="danger": Ersetzt du den shadcn-Button, bricht jedes variant="destructive" in der App. Behältst du ihn, bricht unser Dialog, der Props übergibt, die der shadcn-Button nicht kennt.

Gib der zweiten Bibliothek einen eigenen Ordner. Unsere CLI liest ihre Pfade aus wingo-ui.json. Setz also nach npx wingo-ui@latest init unter aliases den Eintrag "ui": "@/components/wingo". Dann schreibt add dorthin und passt die Imports an. Installier unsere Items mit unserer CLI statt mit der von shadcn: init führt die Design-Tokens in app/globals.css zusammen, das JSON im shadcn-Format unter /r/<slug>.json enthält dagegen keine, und shadow-modal oder z-modal würden ins Leere laufen. Was du sonst prüfen solltest, bevor du eine Registry von Drittanbietern hinzufügst, steht in unserem Guide zu shadcn-Registries.

Funktioniert der shadcn-Skill in Cursor?

Er lässt sich installieren, und Cursor findet ihn, mit zwei Einschränkungen. Der Befehl:

npx skills add shadcn/ui --agent cursor

Er hat zwei Skills, shadcn und migrate-radix-to-base, nach .agents/skills/ kopiert und in skills-lock.json eingetragen. Cursor findet Skills in .agents/skills/ und .cursor/skills/, aus Kompatibilitätsgründen auch in .claude/skills/ und .codex/skills/. Hat das Repository den shadcn-Skill schon für Claude Code, nutzt Cursor diese Kopie mit. Installier ihn also nur einmal.

Beide Einschränkungen gehen auf Felder zurück, die für Claude Code gedacht sind. Die Zeile allowed-tools erlaubt Claude Code, die shadcn-CLI (über npx, pnpm dlx oder bunx) ohne Nachfrage auszuführen; die Skills-Docs von Cursor nennen kein solches Feld, diese Befehle folgen also deinem Run-Modus. Außerdem lädt der Skill deinen Projektkontext mit npx shadcn@latest info --json über die Befehlssyntax von Claude Code, die in den Docs von Cursor nicht vorkommt. Rechne also damit, dass Agent diesen Befehl selbst ausführt. Die Regeln des Skills (Registry nennen, zuerst die shadcn-Doku lesen, Formulare aus FieldGroup bauen) passen zu shadcn/ui-Dateien und nicht zu anderen Registries, deine Regel muss diese Grenze also ziehen.

Was sollten die Cursor-Regeln sagen?

Wem welcher Ordner gehört, mit welchem Tool gesucht wird, welche CLI installiert, welche Tokens gelten und wo shadcn/ui-Muster aufhören. Cursor Rules für React wirken am besten als ein paar Zeilen, an denen Agent sein Ergebnis prüfen kann, denn eine Regel, die immer gilt, kostet in jedem Chat Kontext. Projektregeln liegen in .cursor/rules und brauchen die Endung .mdc; eine normale .md-Datei dort wird ignoriert. Das Frontmatter entscheidet, wann eine Regel lädt: alwaysApply: true für jeden Chat, globs, wenn eine passende Datei im Kontext ist, nur eine description, wenn Agent sie für relevant hält. Ohne all das lädt sie nur, wenn du sie per @ erwähnst. Die alte einzelne .cursorrules-Datei taucht in den Docs von Cursor nicht mehr auf, zieh also alles um, was du dort noch stehen hast.

Für ein Projekt mit zwei Registries würden wir diese Cursor shadcn Rules als .cursor/rules/ui-registries.mdc committen:

---
description: Welche Komponenten-Registry für welchen Ordner zuständig ist, wie Komponenten installiert werden und welche Tokens gelten
alwaysApply: true
---

- Zwei Registries. `components/ui` ist shadcn/ui (`@shadcn` in components.json). `components/wingo` ist Wingo UI (wingo-ui.json); importiere es aus `@/components/wingo/<name>`.
- Vor dem Schreiben von UI suchen: die `shadcn`-MCP-Tools für @shadcn, die `wingo-ui`-MCP-Tools für Wingo UI. Schreib nie eine Komponente von Hand, die eine Registry hat.
- Installiere shadcn-Items mit `npx shadcn@latest add @shadcn/<name>` und Wingo-UI-Items mit `npx wingo-ui@latest add <slug>`. Installiere nie ein Wingo-UI-Item mit der shadcn-CLI.
- Lies die Props der Datei, die du importierst, bevor du sie nutzt. shadcn/ui-Muster (`variant="default"`, `FieldGroup`, ein selbst gebauter Spinner) gelten nur für `components/ui`.
- Farben kommen aus Tokens: `bg-background`, `bg-card`, `text-muted-foreground`, `border-border`. Keine Hex-Werte, kein `bg-blue-500`.
- Übergib nie `--overwrite`. Zeig mir den Diff, bevor du eine Komponente aktualisierst.

Sechs Punkte, jeder prüfbar. Cursor empfiehlt in den Rules-Docs (opens in a new tab), eine Regel unter 500 Zeilen zu halten und neue Regeln erst dann anzulegen, wenn Agent denselben Fehler immer wieder macht. Regeln erreichen nur Agent, nicht Cursor Tab, und User Rules gelten nicht für Inline Edit. Arbeiten Claude Code oder Codex im selben Repository, gehören diese Punkte stattdessen in die AGENTS.md, die Cursor ebenfalls liest; welche Datei welcher Agent lädt, erklärt unser Vergleich von AGENTS.md und CLAUDE.md.

Wie binde ich den MCP-Server einer Bibliothek neben dem von shadcn ein?

Füg einen zweiten Eintrag in dieselbe .cursor/mcp.json ein. Für unsere Bibliothek schreibt ein Befehl sowohl den Server-Eintrag als auch eine Regel für die Bibliothek:

npx wingo-ui@latest agents install cursor

In unserem Testprojekt hat er .cursor/rules/wingo-ui.mdc angelegt, eingegrenzt mit globs: ["**/*.tsx", "**/*.jsx", "**/*.css"], und unseren Eintrag ergänzt, ohne den von shadcn anzutasten:

{
  "mcpServers": {
    "shadcn": { "command": "npx", "args": ["shadcn@latest", "mcp"] },
    "wingo-ui": { "command": "npx", "args": ["-y", "wingo-ui@latest", "mcp"] }
  }
}

Das ist der lokale Proxy, der den Key nutzt, den npx wingo-ui@latest login gespeichert hat. Ist WINGO_UI_API_KEY exportiert, schreibt der Befehl stattdessen den Remote-Server, mit der Variablensyntax von Cursor, damit der Key nicht in der Datei steht: "headers": { "Authorization": "Bearer ${env:WINGO_UI_API_KEY}" }. Unser Server ergänzt, was dem von shadcn fehlt: Props mit Defaults (get_component), Designregeln und Tokens (get_design_rules, get_theme_tokens) und Updates (check_updates). Aktiviere ihn über seinen Schalter, genau wie den von shadcn.

Mit welchen Prompts installiert Agent die richtige Komponente?

Mit denen, die die Registry nennen, vor der Installation eine Suche verlangen und sagen, wie das Ergebnis geprüft wird:

1. Zuerst suchen. „Durchsuch @shadcn und @wingo-ui nach einer Admin-Datentabelle mit Bulk-Aktionen und Karten auf Smartphones. Liste jeden Kandidaten mit Registry und Add-Befehl auf. Installier noch nichts.“
2. Auf der echten API bauen. „Installier data-table und dialog von Wingo UI mit der Wingo-CLI, lies ihre Props mit get_component und bau dann app/clients/clients-table.tsx: Suche, ein Status-Badge, eine Summe der Salden, Zeilenaktionen und einen Bestätigungsdialog vor dem Löschen.“
3. Die Tokens prüfen. „Liste jede Farbklasse in den Dateien auf, die du angefasst hast, und ersetze alles, was kein semantisches Token ist.“
4. Mit einem Check enden. „Führ get_audit_checklist aus, dann Type-Check und Lint für die geänderten Dateien.“

Hier ist die Tabelle, mit der Prompt 2 beginnt. Tipp etwas in die Suche, sortier nach der Spalte „Balance“ und wähl dann zwei Zeilen aus: Die Toolbar wird zur Leiste für Bulk-Aktionen.

Ein guter Durchlauf von Prompt 2 endet mit einer Datei wie dieser, gebaut auf den echten APIs von Data Table, Dialog und Button. Wir haben sie gegen Release 1.9.0 per Type-Check geprüft:

// app/clients/clients-table.tsx
"use client";

import { useState } from "react";
import { Pencil, Plus, Trash2 } from "lucide-react";
// neben shadcn/ui lauten diese Imports @/components/wingo/...
import { Button } from "@/components/ui/button";
import { DataTable, type DataTableColumn } from "@/components/ui/data-table";
import { Dialog, DialogClose } from "@/components/ui/dialog";

export type Client = {
  id: string;
  name: string;
  city: string;
  status: "Aktiv" | "Interessent" | "Überfällig";
  balance: number;
  lastInvoice: string; // ISO-Datum
};

const COLUMNS: DataTableColumn<Client>[] = [
  { id: "name", header: "Kunde", filter: "text", mobile: "title" },
  { id: "city", header: "Stadt", filter: "multi-select" },
  {
    id: "status",
    header: "Status",
    type: "badge",
    badge: {
      Aktiv: { tone: "success" },
      Interessent: { tone: "info" },
      Überfällig: { tone: "danger" },
    },
    filter: "multi-select",
  },
  { id: "balance", header: "Saldo", type: "currency", footer: "sum", filter: "number-range" },
  { id: "lastInvoice", header: "Letzte Rechnung", type: "relative" },
];

type ClientsTableProps = {
  clients: Client[];
  onCreate: () => void;
  onEdit: (client: Client) => void;
  onDelete: (ids: string[]) => Promise<void>;
};

export function ClientsTable({ clients, onCreate, onEdit, onDelete }: ClientsTableProps) {
  const [open, setOpen] = useState(false);
  const [pending, setPending] = useState<Client[]>([]);
  const [deleting, setDeleting] = useState(false);

  function askDelete(rows: Client[]) {
    setPending(rows);
    setOpen(true);
  }

  async function confirmDelete() {
    setDeleting(true);
    try {
      await onDelete(pending.map((client) => client.id));
      setOpen(false);
    } finally {
      setDeleting(false);
    }
  }

  const title = pending.length === 1 ? `${pending[0]?.name} löschen?` : `${pending.length} Kunden löschen?`;

  return (
    <>
      <DataTable<Client>
        data={clients}
        columns={COLUMNS}
        caption="Kunden"
        locale="en-US"
        searchPlaceholder="Kunden suchen"
        selectionMode="multiple"
        toolbarActions={[{ id: "new", label: "Neuer Kunde", icon: <Plus />, onSelect: onCreate, primary: true }]}
        bulkActions={(rows) => [
          { id: "delete", label: "Löschen", icon: <Trash2 />, tone: "danger", onSelect: () => askDelete(rows) },
        ]}
        rowActions={(row) => [
          { id: "edit", label: "Bearbeiten", icon: <Pencil />, onSelect: () => onEdit(row) },
          { id: "delete", label: "Löschen", icon: <Trash2 />, tone: "danger", onSelect: () => askDelete([row]) },
        ]}
      />
      <Dialog
        open={open}
        onOpenChange={(next) => !deleting && setOpen(next)}
        dismissible={!deleting}
        title={title}
        description="Die Rechnungen bleiben in deinen Unterlagen. Das lässt sich nicht rückgängig machen."
        icon={<Trash2 />}
        tone="danger"
        footer={
          <>
            <DialogClose asChild>
              <Button variant="soft" disabled={deleting}>
                Abbrechen
              </Button>
            </DialogClose>
            <Button tone="danger" loading={deleting} loadingText="Wird gelöscht" onClick={confirmDelete}>
              Löschen
            </Button>
          </>
        }
      />
    </>
  );
}

Farben kommen aus Tones, nie aus Klassen, Dark Mode braucht also keinen zusätzlichen Code. Die Liste pending überlebt den Dialog, deshalb springt der Titel nicht auf „0 Kunden löschen?“, während der Dialog ausblendet. Der Lösch-Button nutzt loading statt eines selbst gebauten Spinners. Solange die Anfrage läuft, verhindert dismissible={!deleting}, dass Escape, ein Klick außerhalb oder das Ziehen am Sheet den Dialog schließt, und das abgesicherte onOpenChange sorgt dafür, dass ihn auch der Schließen-Button nicht mitten in der Anfrage zumacht. Es gibt keine Media Query: Unter 768px zeigt die Tabelle Karten, und der Dialog öffnet sich als Bottom Sheet. Server-Modus und die übrigen Props der Tabelle stehen in unserem Guide zur Data Table mit TanStack Table v9.

Warum ignoriert Cursor den MCP-Server oder die Regeln?

Meist aus einem von fünf Gründen:

• Der Server ist aus. Ein Server aus .cursor/mcp.json steht im Chat erst zur Verfügung, wenn sein Schalter unter Customize an ist; bis dahin fehlen seine Tools unter Available Tools.
• Der Server startet nicht. Öffne das Output-Panel (Cmd+Shift+U auf dem Mac) und wähl „MCP Logs“. Ein stdio-Server braucht beim ersten Start Node und Netzwerkzugriff für npx.
• Eine Registry-Variable fehlt. Nutzt eine Registry in components.json ${VAR} in ihren Headern und die Variable ist nicht gesetzt, lässt die shadcn-CLI den ganzen Aufruf mit MISSING_ENV_VARS scheitern, andere Registries eingeschlossen. Exportier sie oder trag sie in .env.local ein.
• Die Regel lädt nie. Prüf die Endung .mdc, dann das Frontmatter: Eine Regel nur mit globs wartet auf eine passende Datei im Kontext. Nimm alwaysApply: true für Regeln zu Registries und Tokens.
• Der Prompt nennt keine Registry. „Füg eine Tabelle hinzu“ überlässt Agent seinem Gedächtnis. Nenn die Registry und sag „zuerst suchen“.

Wo fange ich an?

Arbeitest du nur mit shadcn/ui, führ mcp init --client cursor aus, schalte den Server ein und committe eine Regel mit drei Zeilen: zuerst suchen, mit der CLI installieren, nur Tokens. Wenn du eine zweite Registry willst, die für Smartphones gebaut ist: Button und Dialog aus diesem Beitrag sind kostenlos, und npx wingo-ui@latest agents install cursor ergänzt unseren Server und unsere Regel neben denen von shadcn; den Rest erklären die Doku zum MCP-Server und die Doku zu Coding-Agenten. Die Data Table gehört zu Wingo UI Pro, siehe Preise. Du nutzt Claude Code im selben Repository? Das Claude Code shadcn Setup ist das Gegenstück zu diesem Beitrag, und weitere Guides findest du unter UI mit KI-Agenten bauen.

Häufige Fragen

Wie füge ich den shadcn-MCP-Server zu Cursor hinzu?

Führ npx shadcn@latest mcp init --client cursor im Stammordner des Projekts aus. Der Befehl schreibt einen shadcn-Eintrag in .cursor/mcp.json und installiert shadcn als Dev-Dependency; danach schaltest du den Server in Cursor per Schalter ein und prüfst, ob seine sieben Tools aufgelistet sind.

Wo liegen die Cursor-Regeln für shadcn?

In .cursor/rules, als Dateien mit der Endung .mdc; eine normale .md-Datei ignoriert Cursor dort. Cursor liest außerdem die AGENTS.md im Stammordner des Projekts. Dort sind Regeln besser aufgehoben, die auch Claude Code oder Codex befolgen sollen.

Installiert der shadcn-MCP-Server in Cursor Komponenten?

Nein. Seine sieben Tools lesen nur: Er liefert einen npx shadcn@latest add-Befehl, und Agent führt ihn im Terminal aus, wo der Run-Modus von Cursor entscheidet, ob du ihn vorher bestätigst.

Wird .cursorrules noch unterstützt?

Stand Oktober 2026 erwähnen die Rules-Docs von Cursor .cursorrules gar nicht mehr und beschreiben Projektregeln in .cursor/rules plus AGENTS.md. Verschieb alte Inhalte aus .cursorrules in eine der beiden Stellen.

Kann Cursor shadcn/ui und eine weitere Registry im selben Projekt nutzen?

Ja. Trag die zweite Registry in components.json ein, damit eine Suche beide abdeckt, und gib der zweiten Bibliothek einen eigenen Ordner, denn viele Bibliotheken im shadcn-Stil liefern eine components/ui/button.tsx mit einer anderen API.