uiable-mcp

Published as @codedthemes/uiable-mcp.

MCP server for the uiable shadcn registry. It exposes tools so AI assistants (Claude Code, Cursor, VS Code, …) can discover, install, and generate UI from uiable blocks via natural language.

This is the "Layer 2" custom server. Layer 1 (the standard 7 registry tools) comes for free from npx shadcn@latest mcp once a consumer has @uiable configured.

Protocol support

Speaks MCP 2026-07-28 and every 2025-era revision from the same binary. serveStdio decides the era per connection, so a client that predates 2026-07-28 connects exactly as it always did — there is nothing for a consumer to change or configure.

Tools

| Tool | Purpose | | ----------------- | -------------------------------------------------------------------------------------------- | | list_blocks | List page-level blocks (hero, pricing, feature, footer…), filter by category. | | list_components | List primitive components (button, input, card…), filter by category. | | search_blocks | Ranked keyword/intent search across all items, with previews + install commands. | | get_block | Full details for one item: metadata, files, add command, and a link to its source. | | get_add_command | npx shadcn add command(s) for one or more items (validates names). | | create_ui | Compose a page from blocks for an intent: ordered plan + page.tsx scaffold + add commands. |

Every tool declares an outputSchema and returns structuredContent alongside the serialized text, and is annotated read-only / non-destructive / idempotent.

get_block links each item's source as a resource rather than inlining it; pass includeContent: true when you actually want the file bodies in the result.

Resources and prompts

| URI | Contents | | ----------------------- | ----------------------------------------------------------------- | | uiable://catalog | The full registry index. | | uiable://item/{name} | One item's metadata and the full source of every file it installs. |

The {name} variable is completable from the live catalog. Two prompts — build-page and find-block — wrap the common workflows, with completions on their pageType and category arguments.

Wire into a client

{
  "mcpServers": {
    "uiable": { "command": "npx", "args": ["@codedthemes/uiable-mcp"] }
  }
}

Claude Code (.mcp.json), Cursor (.cursor/mcp.json), VS Code (.vscode/mcp.json) all take the same shape.

Pro items

Pro blocks are listed in the catalog like any other item — only their source is gated. Discovery (list_blocks, search_blocks) needs no credential; installing or reading a pro item does. Generate a token at uiable.com/account and pass it through the client's env block; the server forwards it as a bearer credential and the registry decides entitlement:

{
  "mcpServers": {
    "uiable": {
      "command": "npx",
      "args": ["@codedthemes/uiable-mcp"],
      "env": { "UIABLE_TOKEN": "uia_…" }
    }
  }
}

Items that need a subscription come back marked pro: true (requires the registry's catalog build to emit that flag). Listing results stay cacheScope: "public" — the catalog is identical for every caller — while resources/read becomes "private" once a token is configured, so no shared cache can serve gated source to another caller.

Configuration

| Env var | Purpose | | ------------------ | --------------------------------------------------------------------------- | | UIABLE_TOKEN | Pro registry token. Unlocks pro items; omitted means the public catalog. | | UIABLE_BASE_URL | Registry host. Defaults to https://uiable.com. | | UIABLE_CATALOG | Explicit registry-index.json URL or local file path. Wins over the above. | | UIABLE_NAMESPACE | Install namespace (default @uiable, baked into the catalog). |

When UIABLE_CATALOG points at a local file, item sources are read from r/<name>.json beside it — the layout shadcn build produces — so a local checkout stays self-consistent.

Develop

npm install
npm run build
npm test          # builds, then runs the suite against test/fixtures
npm run inspect   # MCP Inspector against the built server

The test suite covers both protocol eras: 2025-era over a linked in-memory pair, 2026-07-28 by driving createMcpHandler through its own fetch function, plus one end-to-end check that the built binary boots over stdio.

To develop against a local registry build:

UIABLE_CATALOG=/path/to/uiable/public/registry-index.json npm start

Publish

npm publish ships dist/ only. prepublishOnly builds and runs the tests first. publishConfig.access is set to public — required for a scoped package to install for everyone via npx, since npm defaults scoped packages to restricted/private otherwise.