Shadcn.io is not affiliated with official shadcn/ui
search_items
Find any block, component, hook, or icon on shadcn.io by keyword. The default entry point for agents — cheap, fast, and cross-surface.
search_items is the tool your agent reaches for first. Give it a keyword like "pricing" or "chat" and it returns a ranked list of matches across every surface of shadcn.io — blocks, components, hooks, charts, AI, icons, and more.
When to use it
- The user gave you keywords, not slugs ("find me a pricing block with a comparison table").
- You want to see matches across multiple surfaces at once (e.g. a chat block and an AI chat component).
- You're browsing cheaply before committing to
get_itemorget_item_source.
If you already know the surface and want a full dump, use list_items. For category-level block drilling, use list_block_categories → list_blocks_in_category.
Arguments
| Name | Type | Required | Default | Notes |
|---|---|---|---|---|
query | string (min 1 char) | ✓ | — | Case-insensitive substring matched against each item's title |
type | surface enum | — | all surfaces | Restrict results to one surface |
limit | number (1–200) | — | 50 | Raise when cataloguing rather than picking |
Valid type values: blocks, ai, components, examples, hooks, charts, button, background, shaders, text, themes, theme, ui, tools, prompts.
Example prompts
use shadcnio and search for pricing blocks with a comparison tableuse shadcnio to search for anything related to chat across all surfacesuse shadcnio to find the five best hero blocks with "announcement" in the titleName the server explicitly (use shadcnio…) when multiple MCPs are active — without it, the agent may pick another or skip tools entirely.
Response shape
Each row is a lightweight { id, title, url, tag }. Pass the last path segment of url as the slug to downstream tools.
{
"count": 3,
"items": [
{
"id": "/blocks/pricing-grouped-comparison-table",
"title": "React Grouped Comparison Table Pricing Block",
"url": "/blocks/pricing-grouped-comparison-table",
"tag": "blocks"
},
{
"id": "/blocks/pricing-metric-hero-tiles",
"title": "React Metric Hero Tiles Pricing Block",
"url": "/blocks/pricing-metric-hero-tiles",
"tag": "blocks"
},
{
"id": "/blocks/pricing-split-highlight",
"title": "React Split Highlight Pricing Block",
"url": "/blocks/pricing-split-highlight",
"tag": "blocks"
}
]
}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": "search_items",
"arguments": { "query": "pricing", "type": "blocks", "limit": 5 }
}
}' | jq '.result.content[0].text | fromjson'The | jq '.result.content[0].text | fromjson' tail unwraps the JSON-stringified payload so you see the items array directly.
FAQ
Was this page helpful?
Sign in to leave feedback.
MCP Tools Reference
The 15 tools the shadcn.io MCP server exposes — discovery, retrieval, icons, installs, utilities. One page per tool with prompts, responses, and curl examples.
list_items
Dump every item on one shadcn.io surface — blocks, components, hooks, charts, themes, and more. The bulk-view tool for cataloguing.