encode-ui
This server gives AI coding agents a read-only MCP interface to the encode-ui shadcn registry: discover components, read their source, generate exact install commands, and validate brand themes.
Search components — find registry components by name, alias, keyword, or natural-language query, with filters for group, type, motion, and dependency-free status.
Get component metadata — retrieve descriptions, groups, dependencies, provenance/license, source/demo byte sizes, and install commands for a single component.
Read component source — fetch full TSX source files or demo usage examples in fenced code blocks.
Find similar components — discover related components via shared groups, categories, and composition edges.
Enumerate the registry — list all taxonomy groups with counts, and list every component in a group for exhaustive checks.
Generate install commands — produce one
npx shadcn@latest addcommand for multiple components, with unknown names reported.Find or verify Lucide icons — search by concept, verify exact spellings, resolve legacy aliases, and get canonical import names.
Validate brand themes — run WCAG-AA contrast checks, palette-distance math, and generate paste-ready CSS variables via
validate_theme.Serve via MCP — works with Claude Code, Claude Desktop, Gemini CLI, and other stdio MCP hosts; supports optional engines (web/catalog/db) for different search rankings.
Provides verified Lucide icon name lookup, including concept search, category browsing, and legacy alias resolution, so agents can reference correct lucide-react imports.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@encode-ui search for a responsive navbar component"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
encode-ui
Component lookup over the encode-ui registry — 414 shadcn
registry items (361 components + 53 OKLCH palettes), served to AI coding agents over MCP. Your agent searches the catalog, reads any
component's source, and hands back the exact npx shadcn@latest add command.
It also validates a brand theme of your own: validate_theme runs the WCAG-AA clamp and
the uniqueness math the registry's 53 themes each passed, and hands back paste-ready CSS
variables.
Read-only by design. This server tells an agent what to install; installing stays on your own shadcn path, and nothing here touches your project.
Install
One stdio command. npx fetches it on first run — nothing to install or keep current:
npx -y encode-uiZero flags gives you the zero-setup web engine: it fetches the catalog from the deployed registry at startup, caches it, and falls back to a bundled copy, so startup never fails offline. Only three runtime dependencies are required — the native stack behind the semantic engine is optional, so a machine that can't build it still installs and still runs.
Claude Code
The -- is required; without it claude reads the server's flags as its own.
claude mcp add encode-ui -- npx -y encode-uiVerify with claude mcp list (→ ✔ Connected) or /mcp in a session.
Or install the plugin instead, which brings the server plus a brand-theme designer — see Plugin below. Pick one: the plugin registers the server itself, so doing both runs it twice.
Claude Desktop, Gemini CLI, and other hosts
The same JSON block works anywhere that speaks stdio MCP — Claude Desktop's
Settings → Developer → Edit Config, or ~/.gemini/settings.json:
{
"mcpServers": {
"encode-ui": {
"command": "npx",
"args": ["-y", "encode-ui"]
}
}
}Prefer this form when passing flags: they arrive as discrete args that no wrapper can
reinterpret. Restart the host completely after editing. If the server never appears in a
GUI-launched app, it likely didn't inherit your shell's PATH — use an absolute npx path.
ChatGPT is not supported: its connectors accept only remote HTTPS MCP servers, and this one is stdio.
Gated components
A few items need an account. Sign in at encode-ui.com, copy the
token from any gated item's Install tab, and put it in the registration's env block —
not on the command line, where ps can read it:
{ "env": { "ENCODE_UI_TOKEN": "eyJ…" } }Everything else works without it.
Related MCP server: @jpisnice/shadcn-ui-mcp-server
Tools
Tool | What it does |
| Component search — natural language or names |
| Metadata for one component, plus the byte size of its source and demo |
| The full TSX source, or the demo |
| Related components |
| The taxonomy with per-group counts |
| Full membership of one group — the enumeration search can't be |
| One |
| Verified lucide icon names — by concept, or to check a spelling ( |
| Your own brand theme, checked: AA clamp, per-pair contrast, distance from 48 palettes, plus paste-ready |
Every search and list hit carries pure: true when the item's whole install tree adds no
npm packages beyond the shadcn substrate you already have. search_components and
list_components take a dependencyFree filter.
Two behaviours worth knowing. Search is not an oracle of absence — for "does the registry
have X?" or "list everything in Y", enumerate with list_groups then list_components and
judge the descriptions. And a misspelt name is an error, not an empty result: it comes
back carrying the closest matches, so the agent self-corrects in one turn.
Prompts
Two slash commands carry the long-form guidance, at zero token cost until invoked:
Prompt | Slash form |
|
|
|
|
use-registry is the recurring workflow (discover → assess → install → customize);
setup-project is the one-time consumer init — the components.json namespace, the OKLCH
token contract, tw-animate-css, and a smoke test.
Plugin
Claude Code only. The plugin bundles this server together with a
brand-theme-designer agent, the two skills it drives, a slash-command shortcut that
dispatches it, slash forms of the server's two prompts, and a typed command for every
tool — so one install gives you both component lookup and a way to brand your app, all
under the /encode-ui:* umbrella:
/plugin marketplace add reuvenaor/encode-ui
/plugin install encode-ui@encode-ui-theme-genWhat you get | How you reach it |
the MCP server | registered automatically on the db engine (semantic search over the index the package ships; its first query downloads ~1.2 GB of embedding weights, and offline it degrades to lexical) — see the caveat below |
| the shortcut: hand it a brief, it runs the agent end to end |
| designs a full brand from a brief, validates it, writes your CSS, and leaves a brand guide |
| the method: personality tuple, OKLCH role mapping, dark re-derivation, shadow knobs, uniqueness floors |
| where the tokens go in a stock |
| the component workflow — the |
| one-time consumer setup — the |
the nine tools, typed | one command per tool: |
Skills and commands are slash commands; agents are not. The agent is reached by the
shortcut above, by @agent-encode-ui:brand-theme-designer, or by just describing what
you want — there is no / form for an agent in Claude Code. The two prompt wrappers
mirror src/mcp/prompts.ts verbatim, and the command set tracks
the tool surface one-to-one; test/plugin-naming.test.ts goes red if either drifts.
Caveat — do not do both. The plugin registers the server itself. If you already ran
claude mcp add encode-ui, remove it first (claude mcp remove encode-ui), or the server
runs twice and its tools appear under two names (bare, and
mcp__plugin_encode-ui_registry__*). Under the plugin the server shows in /mcp as
plugin:encode-ui:registry, so it sorts under p — it is renamed, not missing.
Not on Claude Code? Plugins are a Claude Code format, but the pieces are not locked to
it. validate_theme is a plain MCP tool that works in any host. And the skills are
plain Agent Skills folders — copy
plugin/skills/brand-design and plugin/skills/theme-tokens into wherever your tool
reads skills from (Cursor, Codex, Copilot and others support the format). The agent
definition and its dispatcher skill are the Claude-Code-specific pieces.
Engines
--registry-engine <web|catalog|db> picks how search works. The default is fine for most
people; the other two trade setup for better ranking.
web (default) — no model, no index. Fetches the catalog from the registry, and source bodies per call. Its search is a plain filter over names, aliases and keywords, so behaviour-style discovery works best by reading the
encode-ui://catalogresource once and letting the model judge the descriptions.catalog — offline lexical ranking over the bundled index. Ranking never touches the network; source bodies still come from the origin (or a registry checkout, if one surrounds the package).
db — hybrid semantic + lexical retrieval over each component's description, full source, and demo. The strongest for vague, behaviour-style queries. Served from the
index.dbshipped in the package; the first query downloads ~1.2 GB of ONNX weights once per machine (--lexical-onlyskips the model entirely).
Configuration
Every install-time property is a flag; --help prints this to stderr. The only
configuration environment variable is ENCODE_UI_TOKEN.
Flag | Engine | Effect |
| — | Which engine serves the tools. Unset = |
| db | Path to |
| web, catalog | Origin bodies are fetched from. Default |
| catalog | Registry checkout to read source bodies from. |
| db | Where ONNX weights are cached. Default |
| db | Skip the model; FTS5-only. Results flagged |
| — | Print usage / version to stderr and exit. |
A flag the selected engine would ignore is a usage error (exit 2), same as a malformed
value — the server never warn-and-ignores something you typed deliberately. Path flags
expand ~ and resolve relative values against the server's cwd.
Gotchas
Rebuilding the index means restarting every running server. The build replaces
index.dbwith a new file, while the server opens it once and holds the handle — so a long-lived server keeps serving the deleted snapshot, silently. After a rebuild, reconnect and check that the startup banner's item count matches.Icons are data, not components. The registry ships no icon components;
find_iconsanswers from vendored lucide metadata at the exact tag the registry pins forlucide-react. Ask it rather than guessing an import.
License
MIT, Copyright (c) 2026 Reuven Naor — see LICENSE. This package ships a prebuilt
index carrying component source, some of it adapted from other MIT-licensed projects; their
notices travel with it in NOTICE.md. The bundled agent-index.json is generated
from the registry, so regenerating it is a maintainer task rather than something a clone can
reproduce.
Questions, licensing or otherwise: info@reuvenaor.com.
Available Tools
8 toolsfind_iconsFind or verify lucide iconsARead-only
Verified lucide-react icon names — never guess an icon import. Two modes (at least one of query/names/category is required): query searches names, curated tags, and categories by what the icon should depict ("shopping cart", "danger warning"); names verifies exact spellings and resolves legacy aliases (Home → House, with the deprecation flagged). category filters or browses. Hits carry the canonical name, the import identifier, and tag/category context; the registry itself ships no icon components — lucide-react 0.511.0 is the icon layer, auto-installed with any icon-using item.
Inputs: limit, names, query, category. Returns: count, icons, usage, install, +2 more
find_similarFind similar componentsARead-only
Components related to a given one — same group, shared categories, and composition edges, computed from the fetched registry index. Useful for "what else is like this" and for finding variants. score is a structural heuristic (scoreKind "lexical"), comparable only within one result set; these are not embedding-space neighbours.
Inputs: name (required), k. Returns: seed, count, engine, neighbours
get_componentGet a encode-ui componentARead-only
Metadata for one component by name: description, group, dependencies, provenance/license, and the install command. Reports the byte size of the source and demo without sending them — fetch those from get_component_source once you know what they cost.
Inputs: name (required). Returns: name, type, gated, group, +19 more
get_component_sourceGet a component’s sourceARead-only
Every TSX file one component ships, or its demo usage example, in fenced code blocks. A multi-file component returns ALL of its files — the public module plus every sibling it imports (.parts.tsx pairs, block modules) — because the entry file alone does not compile. Check sourceBytes/demoBytes on get_component first if size matters. Returns code as text rather than a JSON field, so it stays readable.
Inputs: name (required), part.
get_install_commandGet the install commandARead-only
One npx shadcn@latest add command installing all the named components at once. Duplicates collapse; names with no such component come back under unknown.
Inputs: names (required). Returns: command, unknown, components
list_componentsList a group’s componentsARead-only
Every component in one group — full membership, not a ranked sample. Search always returns its top k, so "list ALL X" and "does the registry have X?" need this instead: enumerate, then judge the descriptions yourself. Returns name, title, and description per item; get_component has the details.
Inputs: group (required), dependencyFree. Returns: count, group, engine, components
list_groupsList component groupsARead-only
The registry taxonomy with a component count per group. Use a slug from here as the group filter on search_components, or enumerate a group in full with list_components.
Inputs: no named parameters. Returns: engine, groups, totalItems
search_componentsSearch encode-ui componentsARead-only
Find React components in the encode-ui registry by name, alias, or keyword. Web engine: a plain substring filter over the index fetched from the deployed registry (name, aliases, curated keywords, title, description) — exact names and aliases ("modal", "toast") work best; loose behaviour phrasing may miss. Terms split on punctuation and single characters are dropped, so "toast?" and "a dialog." behave like the bare words. For discovery and planning, read the catalog resource encode-ui://catalog (≈20k tokens) once and judge the descriptions yourself. Every hit carries the exact install command. score is rank-derived (scoreKind "lexical"), comparable only within one result set, and cosine is always null — no score here is calibrated. A filter cannot prove absence: for "find ALL X" or "does the registry have X?" use list_groups + list_components and judge the descriptions yourself.
Inputs: query (required), k, type, group, +2 more. Returns: hits, count, query, engine, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: searching, finding similar, fetching metadata, fetching source, listing groups, listing components, getting install commands, and finding icons. The descriptions explicitly clarify differences (e.g., search_components vs list_components), so there is no ambiguity.
Most tools follow a verb_noun pattern (search_components, get_component, list_groups, list_components, find_icons). Minor deviations include find_similar (verb + adjective) and compound nouns like get_component_source and get_install_command, but these are still readable and predictable.
With 8 tools, the set is well-scoped for a component registry server. Each tool covers a distinct aspect of discovery and installation without redundancy, fitting the typical 3-15 tool sweet spot.
The tool surface covers the full read/install workflow: searching, browsing by group, enumerating, getting metadata, getting source, getting install commands, and verifying icons. No obvious gaps exist for the server's stated purpose of exploring and installing components.
Maintenance
Related MCP Connectors
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Web search API and MCP server for developers building AI agents.
Search, vet & assemble MCP servers from your agent: verified tools, risk labels, and trust scores.
Search a directory of 70K+ AI building blocks: MCP servers, agents, models, datasets, prompts.
Related MCP Servers
- AlicenseAqualityDmaintenanceHelps AI assistants access shadcn/ui component documentation and examples through a TypeScript-based MCP server that provides reference information for component details, usage examples, and search capabilities.4739 npm60MIT
- AlicenseAqualityBmaintenanceA mcp server to allow LLMS gain context about shadcn ui component structure,usage and installation107,183 npm3,098MIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive template for building MCP servers that expose UI component registries and design systems to AI assistants. It enables users to browse, fetch, and retrieve implementation details from registries following the shadcn/ui format.177 npm2MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server provides tools to install and manage shadcn/ui components directly from AI coding agents.2MIT