MCP server

What your assistant can do

• search_blocks: search the catalog with a plain description like "hero with an image on the right and a testimonial quote". Returns ranked matches with install commands, the top few pictured.
• get_block: look up one block by its registry item name and get its description, install command, and light and dark captures.
• list_collections: list the collections your key covers with their groups and block counts, useful for scoping a search.
• get_designer_file: read a Designer file by its name and get each page's blocks in order with their install commands.

Clients that draw images in the chat, like Claude Desktop and Cursor, show those captures beside the results. The rest keep each block's preview link.

How installs work

Every result carries a command for the Shadcn CLI that points at the block's own registry URL, so your assistant can run it straight away. Free and community blocks install from a plain URL. Premium and standard blocks install from a URL that carries a token issued against your key and good for an hour, which stands in for the registry entry and API key the CLI guide sets up, so nothing is written to your project's components.json. If a token has expired by the time you run the command, ask for the block again and a fresh one comes back.

The CLI does the rest: it writes the block's source at the right paths, installs its npm dependencies, and adds the shadcn/ui components it builds on.

Hand over a Designer file

Draft a page in the Designer, then ask your assistant for it by name, for example "Pull Landing v3 in and install every section." The server reads the file from the workspace your API key was made in, so a key made in a team reads that team's files. Blocks your plan cannot install come back marked locked, so your assistant can tell you before anything fails.

Connect the server

1. 1

   Create an API key

   Sign up for a free account, then create a key on the API keys page. It is shown once, so copy it somewhere safe.

2. 2

   Add the server to your client

   Every MCP client speaks to it the same way: a streamable HTTP server at the URL above, with your key as a bearer header. Pick your client for the exact config, then keep the key out of your repository:

   CursorClaude CodeCodexVS CodeAny client

   ~/.cursor/mcp.jsonCopy

   {
     "mcpServers": {
       "shadcn-ui-blocks": {
         "type": "http",
         "url": "https://www.shadcn-ui-blocks.com/api/mcp",
         "headers": {
           "Authorization": "Bearer sk_live_your_key_here"
         }
       }
     }
   }

   • Cursor: put the config in the global ~/.cursor/mcp.json with your key in place of the placeholder, so it never lives in a project.
   • Claude Code: the command reads the key from SHADCN_UI_BLOCKS_API_KEY in your shell, or paste the key in its place when you run it.
   • Codex: the entry goes in ~/.codex/config.toml and reads the key from SHADCN_UI_BLOCKS_API_KEY in your shell, so the file never holds it.
   • VS Code: the config asks for the key the first time the server starts and keeps it out of the file, so it is safe to commit.
   • Any other client: add a streamable HTTP server with the URL and the header; use its own secret store for the key where it has one.
3. 3

   Describe the block you need

   Ask your assistant in plain words and let it search. For example:

   • "Find me a pricing section with a comparison table."
   • "I need a hero with an app screenshot on the right, search Shadcn UI Blocks."
   • "What testimonial blocks with star ratings are available?"
4. 4

   Install the match

   Ask your assistant to install it, or run the command from the result yourself in your project root. A premium or standard one looks like this:

   TerminalCopy

   npx shadcn@latest add "https://www.shadcn-ui-blocks.com/r/modern-saas-hero-sections-centered-with-backdrop.json?token=<token>"

   Prefer to install by name from your own terminal, without the assistant? The Shadcn CLI guide wires the registry into your project once, after which any block your plan covers installs as npx shadcn@latest add @shadcn-ui-blocks/<block>.

Next steps

• Browse the block catalog
• Set up the Shadcn CLI