list_popular

list_popular is where analytics meets the agent. Every shadcn add install fires a tracking event into the analytics DB, which maintains ComponentStats with aggregated downloadCount, viewCount, and pageViewCount per item. This tool reads that table sorted by downloads.

When to use

• The user asks for "a good X block" without specifying — list_popular returns the ones other users actually install.
• When several siblings in a category look similar, popularity disambiguates.
• For marketing/social-proof prompts: "which blocks are trending on shadcn.io?"
• As a tiebreaker between candidates surfaced by search_items.

How it works

1. One Prisma query against analyticsDb.componentStats:

   SELECT component_name, component_type, category,
          download_count, view_count, page_view_count,
          first_download_at, last_download_at
   FROM component_stats
   WHERE component_type = $1   -- if `type` is provided
   ORDER BY download_count DESC
   LIMIT $2

2. The table has a matching composite index (componentType, downloadCount DESC), so the query is an index scan — microseconds even at tens of thousands of rows.
3. No aggregation, no joins, no cross-DB lookups. One network round-trip to Postgres.

If the deployment has no analytics DB configured (ANALYTICS_DATABASE_URL unset), the tool returns an error — surface that clearly in agent output.

Arguments

Response

{
  "count": 5,
  "items": [
    {
      "componentName": "hero-announcement",
      "componentType": "blocks",
      "category": null,
      "downloadCount": 12483,
      "viewCount": 47102,
      "pageViewCount": 91284,
      "firstDownloadAt": "2025-09-14T12:04:11.000Z",
      "lastDownloadAt": "2026-04-16T13:58:22.000Z"
    },
    {
      "componentName": "pricing-three-columns",
      "componentType": "blocks",
      "category": null,
      "downloadCount": 9847,
      "viewCount": 38104,
      "pageViewCount": 71293,
      "firstDownloadAt": "2025-08-02T09:11:44.000Z",
      "lastDownloadAt": "2026-04-16T14:02:08.000Z"
    }
  ]
}

• componentName is the slug — feed directly to get_item, get_item_source, or get_install_command.
• firstDownloadAt proxies "when the block first went live" (or was first installed via CLI).
• lastDownloadAt tells you whether the block is still active; stale entries mean trending-down.

Example prompts

use shadcnio to give me the 10 most popular pricing blocks

use shadcnio list_popular with no filter and show me what's trending across every surface

use shadcnio — of the hero blocks, which ones should I actually use?

Manual invocation

curl -s -X POST "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_popular","arguments":{"type":"blocks","limit":10}}}' \
  | sed -n 's/^data: //p' | jq '.result.content[0].text | fromjson | .items'

Tips + gotchas

• All-time downloads, not window-bounded. The underlying downloadCount is cumulative. For "trending this week" we'd need time-series data — a future enhancement. Items with a very recent lastDownloadAt are still active.
• Not every slug in this list is still in the registry. If a block was removed, stats persist in the analytics DB. Chain with get_item if you want to confirm a slug still resolves.
• Filter by surface to get apples-to-apples. Blocks get installed far more than hooks, so an unfiltered list_popular will always be dominated by blocks.
• Indexed query — don't worry about limit: 100 performance. The cost is in network, not database.
• No caching at this layer. The data changes on every install, so fresh-reading is correct. If you want a cached, lower-churn "top 10 ever" view, consider wrapping this tool's output with a client-side cache.