21st.dev Magic MCP: Complete Guide (2026)

TL;DR + what you actually need

• What it is: an MCP server that generates React UI components from natural language. “It’s like v0, but inside your Cursor/Windsurf/Cline” — that’s the project’s own one-liner, and it’s accurate.
• One secret: an API key from 21st.dev/magic/console, passed as the API_KEY environment variable. No key, no generations.
• One package: @21st-dev/magic — an MIT-licensed stdio server that runs via npx. There is no self-hosted model runtime: Magic is a thin client that calls 21st.dev’s hosted generation API.
• The stack it emits: React + TypeScript on shadcn/ui, Tailwind CSS, and Radix. Not Vue, not Svelte, not vanilla JS.

The fastest install, if that’s all you came for:

# CLI installer — pick your client
npx @21st-dev/cli@latest install claude --api-key YOUR_KEY
# clients: cursor · windsurf · cline · claude

Then, in your agent’s chat: type /ui a responsive navbar with a mobile menu and approve the tool call. Full per-client config is in the install section.

What 21st.dev Magic is (for searchers who found the name first)

21st.dev is a React component marketplace — a library of community-published UI components built on shadcn/ui and Tailwind. Magic is the MCP bridge to it. Instead of browsing the site, copying a component, and pasting it into your editor, you describe what you want to your AI agent and Magic fetches or generates it in place. The comparison people reach for is Vercel’s v0: text in, UI out. The difference is where it runs — v0 lives in a browser tab; Magic lives inside the editor agent you’re already coding in.

It was built by the 21st.dev team (founder Serafim, @korablev) and is open source at github.com/21st-dev/magic-mcp under the MIT license. The server is small; the intelligence is 21st.dev’s hosted API and its component catalog, which is why you need an API key and why generations count against a quota. As of mid-2026 the team also shipped an interactive twist — search results can come back as an inline card gallery inside the chat, not a wall of JSON:

That feature rides on the emerging MCP Apps / UI extension work — servers returning rendered widgets rather than plain text. It’s a useful signal that Magic is still getting attention, even as 21st.dev’s public roadmap has leaned toward its broader Agents SDK.

How it works: the mental model

Magic is a stdio process — a local subprocess your MCP client launches — that exposes four tools to the model. When you type a slash command, the agent picks the matching tool, calls 21st.dev’s API, and writes the result into your working tree. The flow for the common case:

You:  /ui a pricing table with a monthly/annual toggle
        │
        ▼
  IDE agent  (Cursor · Claude Code · VS Code · Windsurf · Cline)
        │  chooses + calls the tool
        ▼
  21st_magic_component_builder ──► 21st.dev hosted API + component library
        │                              (shadcn/ui + Tailwind sources)
        ▼
  React + TypeScript component written into your project

The four named pieces, each a tool the model can call:

Our takeaway: the builder is the headline, but the inspiration tool is the underrated one. It returns real snippets from the library so the model works from a proven component instead of hallucinating markup — the same reason a human browses the catalog first.

The /ui, /21, and /21st commands

A point of confusion worth clearing up: /ui, /21, and /21st are not three separate features. They are trigger phrases that the tool descriptions tell the model to watch for. In the server source, the builder’s description literally says to fire “when the user mentions /ui, /21, /21st, or asks for a button, input, dialog, table, form…” So:

• /ui <description> — the default: build a new component, or refine the current one.
• /21 — an alias for the same builder path; interchangeable with /ui in practice.
• /21st or “get inspiration from 21st.dev” — routes to the inspiration tool, which returns library components without writing code.

Because these are prompt conventions rather than a parser, they degrade gracefully. If you forget the slash and just say “use Magic to build a testimonial carousel,” a capable agent still calls the right tool. The slash is a hint, not a keyword the system requires.

Auth: the 21st.dev API key

Magic has one credential: an API key created in the Magic Console. Sign in, generate a key, and copy it. The MCP server receives it through the API_KEY environment variable (or, in the README’s manual config, as an API_KEY="…" argument). Every generation is authenticated with that key and counts against your account’s quota.

Two operational notes from the repo’s issue tracker. First, key creation has been flaky at times — several reports describe “Failed to create API key” errors originating in the console backend, so if the first attempt fails, retry or check the console rather than your MCP config. Second, there is no self-service key rotation in the console today (an open request), so treat the key like any production secret: keep it out of committed files and out of screenshots.

Install (every client)

Magic is stdio-only — your client launches npx -y @21st-dev/magic@latest as a subprocess with API_KEY set. The install panel below pulls its config from the canonical /servers/magic catalog entry, so the package name and shape stay in sync. Pick your client, copy, paste your key, restart.

One-line install · Magic

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

The maintainers ship a CLI that writes the config for you — the recommended path:

npx @21st-dev/cli@latest install <client> --api-key <key>
# <client> = cursor | windsurf | cline | claude

Client-specific notes:

• Cursor — the most common home for Magic. Config lives in ~/.cursor/mcp.json; the CLI writes it, or paste the JSON from the install card. See /clients/cursor.
• Claude Code — add it as a stdio server. If you prefer the manual JSON, drop the @21st-dev/magic block into your MCP config and restart; verify with claude mcp list. Reference at /clients/claude-code.
• VS Code — the README ships a one-click install button and a .vscode/mcp.json block that prompts for the key as a masked input, so the secret never lands in the file.
• Windsurf — config at ~/.codeium/windsurf/mcp_config.json.
• Cline — supported (marked beta in the README); config at ~/.cline/mcp_config.json.

Manual config, if you skip the CLI, is the same block on every client:

{
  "mcpServers": {
    "@21st-dev/magic": {
      "command": "npx",
      "args": ["-y", "@21st-dev/magic@latest", "API_KEY=\"your-api-key\""]
    }
  }
}

One compatibility caveat: Magic’s tool names have tripped up non-Anthropic runtimes. There are open issues about the tool naming violating Gemini’s function-calling rules and about Codex CLI support, so if you’re on Gemini CLI or Codex, check those threads before assuming it works. Cursor, Claude Code, VS Code, and Windsurf are the well-trodden paths.

The four tools, one at a time

21st_magic_component_builder

The headline tool. It takes your description, calls 21st.dev’s generation API, and returns a complete React + TypeScript component that the agent writes into your project. The generated code assumes shadcn/ui — the tool’s own instructions tell the model to install any missing shadcn components and fix imports — so it slots into an existing shadcn project cleanly and needs a bit of setup in a project that doesn’t use shadcn yet. Example:

/ui a settings page with a sidebar, tabbed sections,
    a dark-mode toggle, and a danger-zone card at the bottom

21st_magic_component_inspiration

The browse-before-you-build tool. It returns matching components and previews from the 21st.dev library as structured data — no code is written. Use it when you want to see options (“show me a few hero-section layouts”) and then hand the one you like to the builder. This is also the tool behind the inline card gallery in the maintainer’s July demo above.

21st_magic_component_refiner

The improve-what-you-have tool. Point it at an existing component and ask for a redesign — “make this form match the rest of the app and add inline validation.” It’s the tool most likely to touch code you wrote by hand, so review its diff carefully rather than accepting blind.

logo_search

The odd-one-out, and a genuine time-saver. It searches SVGL’s catalog of brand logos and inserts them as JSX, TSX, or raw SVG. “Add the GitHub, Google, and Discord logos to the login buttons” becomes one tool call instead of a hunt through a logo site. It has nothing to do with UI generation, but it’s bundled because it removes the same kind of copy-paste chore.

Note: the catalog page on mcp.directory doesn’t enumerate individual tool schemas for Magic, so treat this list — sourced from the server’s own src/tools/ directory — as the authoritative one.

Recipes: where Magic earns its quota

Four workflows where the install pays for itself. All assume Magic is registered with a valid key and you approve each tool call.

Recipe 1 — Scaffold a component you’d otherwise copy from a library

“/ui a data table with sortable columns, pagination, and a search input, styled to match my shadcn theme.” This is the sweet spot: a standard, well-solved component that the library has many examples of. Magic returns something 90% done, and you spend your time on the 10% that’s specific to your data.

Recipe 2 — Explore options before committing

“Show me a few pricing-section layouts from 21st.dev, then build the second one with my three tiers.” Inspiration tool first (returns candidates), builder second (writes the chosen one). Faster than opening the site, and the agent keeps your project context while it picks.

Recipe 3 — Wire up brand logos

“Add SVG logos for Stripe, Slack, and Notion to the integrations grid.” logo_search pulls clean SVGs from SVGL and inlines them. No downloading, no favicon-quality PNGs, no licensing guesswork on the common brand marks.

Recipe 4 — Refactor a rough first draft

“This modal works but looks unfinished — refine it: consistent spacing, a proper header, and a loading state.” The refiner is good at the polish pass on a component that’s functionally done but visually rough. It’s weaker at large multi-component layouts — keep the scope to one component per call.

What we got wrong

Three assumptions that cost us time when we first ran Magic, in case they save you some.

We assumed it generated code locally. It doesn’t. Magic is a thin client — the component is generated by 21st.dev’s hosted API, and every call needs network access and burns a generation from your quota. That reframes the free tier: it’s not “free forever,” it’s a trial. Budget accordingly before you build a workflow around it.

We assumed the output would drop into any React project. The output is shadcn-flavored. In a project already on shadcn/ui and Tailwind, it’s seamless. In a plain Create-React-App or a CSS-modules codebase, the generated component arrives with shadcn imports you don’t have, and you’re either installing shadcn or rewriting the styling. Know your stack first.

We treated the generated file as done. It’s a starting point, not a finished component. Accessibility attributes, real loading and error states, and your actual data wiring are still your job. The honest framing from one reviewer stuck with us: it’s “great for single components, less so for full layouts.”

The security caveat you should read before shipping

Magic fetches component code from a community library and hands it to your agent, which can then write files in your repository. That is a supply-chain surface. An open security advisory (issue #46) on the repo spells out the risk: a malicious component published to the library could embed prompt-injection instructions in a code comment or a variable name. When Magic fetches that snippet, the text enters your agent’s context, and a naive agent could follow it — introducing a backdoor, exfiltrating a secret, or editing files beyond the component.

This isn’t a reason to avoid Magic — it’s the same trust model as installing an npm package or copying a Stack Overflow snippet. But the advisory has sat open for a while, so the guardrail is yours to enforce, not the tool’s.

Limits and the fine print

• React + shadcn only. No Vue, Svelte, Angular, or vanilla JS. The output is tied to the shadcn/ui + Tailwind + Radix stack. This is the single biggest “is it for me” filter.
• Hosted, not local. Generation happens on 21st.dev’s servers. No offline use, and your prompts and context travel to their API. Consider that before using it on sensitive codebases.
• Small free tier. The free allotment is a handful of generations; serious use means a paid plan. Because pricing has moved during beta, verify the current numbers in the console rather than trusting any blog (including this one) on the exact figure.
• Reliability wobble. The issue tracker has recurring reports of the builder returning [object Object] or internal errors, especially in Claude Code, and of the refiner returning canned “high load” responses. Usually transient; occasionally not.
• Single-component sweet spot. It shines on one bounded component per call and struggles with whole-page, multi-component layouts. Decompose big UIs yourself and feed Magic the pieces.

Community signal

Magic was one of the early “wow” MCP servers — it makes a great demo, and it circulated widely on r/mcp and in the “servers I actually use” roundups on r/ClaudeAI when MCP tooling was new. The appeal is immediate: watching a described component materialize in your editor is the kind of thing that sells the whole MCP idea.

The measured reviews land in the same place we did. A hands-on review at apidog praised the speed (“under 100ms per request”) but flagged the “tiny free tier” where “five requests vanish fast,” concluded it was “great for single components, less so for full layouts,” and noted that error messages weren’t very helpful when something went wrong. That’s a fair summary: fast and impressive on the happy path, thin on quota, and rough at the edges.

The contrarian read, which we think is correct: Magic is a productivity tool for a narrow slice of work (scaffolding React components in a shadcn project), not a general frontend agent. If you expected it to build your app, you’ll be disappointed; if you expected it to save you the copy-paste round trip to a component library, it delivers. See our best MCP servers for design (2026) for how it stacks up against alternatives, and the ui-ux-pro-max skill if you want a prompt-side approach to the same problem.

The Verdict

Troubleshooting

Frequently Asked Questions

Sources

• Primary repo: github.com/21st-dev/magic-mcp (MIT) — README, and the tool definitions in src/tools/ (create-ui, fetch-ui, refine-ui, logo-search).
• API key + generation: 21st.dev/magic/console and 21st.dev/magic.
• Maintainer post (inline card gallery / MCP Apps): @korablev, July 4, 2026.
• Security advisory: 21st-dev/magic-mcp#46 — prompt injection via fetched component code.
• Reliability reports: magic-mcp#55 (and #58, #68).
• Hands-on review: apidog — I Tried 21st.dev Magic MCP.
• Community thread: r/mcp — 21st.dev Magic AI Agent.
• Canonical MCP.Directory entry: /servers/magic