list_block_categories

Blocks are the biggest surface on shadcn.io (~6000+ items) and the main revenue driver. Rather than making agents search blindly, list_block_categories returns the 56 thematic categories so the agent can drill category-first before slurping slugs.

When to use

• The agent wants to scaffold a multi-section page and needs the vocabulary ("we have hero, pricing, cta, testimonials, …").
• Before calling list_blocks_in_category — you need the category name.
• Answering "what kinds of blocks do you have?" prompts.

For non-block surfaces there's no category layer — use list_items directly.

How it works

1. Reads content/blocks/meta.json (the site's left-nav definition).
2. Parses the pages array.
3. Filters to entries wrapped in parens ((hero), (pricing)) — these are Fumadocs route groups, which also happen to match the folder names under packages/blocks/.
4. Strips the parens and returns them in original order.

Result is module-cached on first call.

Source: lib/mcp/content-loader.ts#loadBlockCategories.

The pages array in content/blocks/meta.json looks like:

["---Introduction---", "index", "(about)", "(account)", "(ai)", "(awards)", "..."]

Only the (…) entries make it through.

Arguments

None.

Response

{
  "count": 56,
  "categories": [
    "about", "account", "ai", "awards", "banner", "billing", "blog",
    "calendar", "carousel", "changelog", "chat", "checkout", "command-menu",
    "comments", "contact", "crud", "cta", "dashboard", "dialog",
    "empty-state", "error", "faq", "features", "file-upload", "footer",
    "form", "gallery", "hero", "integration", "kanban", "login", "logos",
    "map", "monitoring", "music", "navbar", "notification", "onboarding",
    "pricing", "product-cards", "profile", "reviews", "search", "settings",
    "sidebar", "skeleton", "stats", "stepper", "storefront", "success",
    "tables", "team", "testimonials", "timeline", "todo-list", "web3"
  ]
}

Example prompts

use shadcnio to list every block category

use shadcnio and tell me what kinds of marketing sections you have

use shadcnio to pick 6 categories that would make a complete SaaS landing page

Manual invocation

curl -s -X POST "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_block_categories",
      "arguments": {}
    }
  }' | jq '.result.content[0].text | fromjson | .categories'

Tips + gotchas

• Order reflects the nav — the array is in the exact order the left-side navigation shows on /blocks. Agents that want alphabetical order should sort on the client.
• Block URLs are FLAT — /blocks/hero-announcement, not /blocks/hero/hero-announcement. Category folders (hero) are route groups; the parens are not part of the URL. Slugs typically start with the category prefix by convention.
• Categories map to filesystem folders — every returned name is the directory name under packages/blocks/. That's why list_blocks_in_category can scan packages/blocks/{category} directly.
• Cache is process-local — new categories require a server restart or rebuild to appear.