ui-mcp

A local MCP server that gives Claude Code (and any MCP client) access to a curated registry of elite UI patterns, components, and motion configs — so it pulls real, copy-pasteable implementations mid-build instead of defaulting to generic layouts.

Magnetic cursors, scroll-jacked sections, reactive particle grids, clip-path page transitions, text-scramble reveals, glassmorphic navs, spring modals, bento grids, and more — every entry ships real working React/TSX, valid Tailwind classes, and Framer Motion / GSAP / CSS motion values.

• 30 UI patterns (clean · elevated · insane)
• 20 components keyed by type (hero, nav, card, modal, scroll-section, cursor, overlay, loader, text-reveal, background)
• 15 ready-to-paste motion configs (Framer Motion, GSAP, CSS)
• Fuzzy natural-language search via Fuse.js

---

Install & setup

git clone https://github.com/maahigoel/ui-elite-patterns.git
cd ui-elite-patterns
npm install
npm run build

This compiles src/ → dist/. The server entry is dist/server.js.

Add to Claude Code

A ready-to-use .mcp.json is included:

{
  "mcpServers": {
    "ui-mcp": {
      "command": "node",
      "args": ["dist/server.js"]
    }
  }
}

• Project scope: copy .mcp.json into your project root and run Claude Code from there. (If args is a relative path, run Claude Code from the ui-mcp directory, or change it to the absolute path of dist/server.js.)
• CLI: claude mcp add ui-mcp -- node /absolute/path/to/ui-mcp/dist/server.js

Restart Claude Code, then ask it to use the ui-mcp tools. Verify the server boots:

npm run smoke   # builds, boots the server in-memory, and exercises every tool

---

Live demo site

A local showcase website that renders every pattern and component live lives in demo/. It uses a codegen script that pulls each component straight from this registry, so it always reflects exactly what the MCP server hands to Claude Code.

cd demo
npm install
npm run dev        # generates components from the registry, then starts Vite at http://localhost:5173

• Browse all 50 patterns + components in a filterable gallery (search, complexity, kind).
• Click any card to view it full-screen, running live, with a slide-in source panel + copy button.
• npm run generate re-syncs the demo with the registry after you add patterns. (npm run dev/build run it automatically.)

Built with Vite + React + Tailwind + Framer Motion. Local only — no hosting required.

---

Tools

1. get_ui_pattern

Fuzzy-search the registry by natural language.

Input

field	type	required	description
query	string	✅	What you want, e.g. "magnetic cursor"
framework	"react" | "vue" | "html"	–	Filter by framework support
complexity	"clean" | "elevated" | "insane"	–	Filter by complexity

Example

// input
{ "query": "scroll reveal headline", "complexity": "insane" }

// output (truncated)
Found 3 matching patterns for "scroll reveal headline". Showing the top 3:

## Text Scramble Reveal on Scroll
**Complexity:** insane • **Frameworks:** react • **Interaction:** scroll
**Tags:** text, scramble, decode, scroll, reveal, monospace, raf
...
### Code
```tsx
import { useEffect, useRef, useState } from "react";
...

### 2. `get_component`

Get component(s) of a given type.

**Input**

| field | type | required | description |
| --- | --- | --- | --- |
| `type` | `hero \| nav \| card \| modal \| scroll-section \| cursor \| overlay \| loader \| text-reveal \| background` | ✅ | Component kind |
| `interaction` | `scroll \| hover \| entrance \| ambient` | – | Preferred interaction |
| `complexity` | `clean \| elevated \| insane` | – | Preferred complexity (nearest returned if exact missing) |

**Example**

```jsonc
// input
{ "type": "modal", "complexity": "elevated" }

Returns the Spring Modal with Blur Backdrop with full TSX and its Framer Motion config. Omit complexity to get every variant of that type (clean → insane).

3. get_motion_config

Get a paste-ready motion configuration.

Input

field	type	required	description
type	page-transition | entrance | scroll-reveal | hover | stagger | magnetic	✅	Motion kind
library	framer-motion | gsap | css	–	Filter by library

Example

// input
{ "type": "stagger", "library": "framer-motion" }

// output (truncated)
## Framer Motion Stagger Children (0.08s)
**Type:** stagger • **Library:** framer-motion
### Config
```json
{ "config": { "staggerChildren": 0.08, "delayChildren": 0.1 }, "variants": { ... } }

Code

const container = { hidden: {}, visible: { transition: { staggerChildren: 0.08, delayChildren: 0.1 } } };
...

Usage: Put container on the parent and item on each child; the parent drives timing.

---

## Example prompts inside Claude Code

- *"Use ui-mcp to find a magnetic cursor pattern and add it to my landing page."*
- *"Get me an `insane` complexity background component from ui-mcp for the hero."*
- *"Build a pricing section — grab the pricing card pattern from ui-mcp first."*
- *"I need a page transition. Pull the Framer Motion `page-transition` config from ui-mcp."*
- *"Find a scroll-jacked horizontal section in ui-mcp and wire it up with my project's content."*
- *"Get the `text-reveal` component (elevated) from ui-mcp and use it for the section heading."*

---

## Contributing — add a pattern

The registry lives in `src/registry/`:

- `patterns.ts` — patterns surfaced by `get_ui_pattern`
- `components.ts` — components surfaced by `get_component` (must set `componentType`)
- `motion.ts` — configs surfaced by `get_motion_config`

Add a new entry to the relevant array following the `RegistryEntry` shape (`src/types.ts`):

```ts
{
  id: "my-pattern",                 // unique kebab-case id
  name: "My Pattern",
  tags: ["..."],                    // drives fuzzy search — be generous
  complexity: "elevated",           // "clean" | "elevated" | "insane"
  framework: ["react"],
  componentType: "card",            // components only — enables get_component
  interaction: "hover",             // optional
  description: "One sentence on what it is.",
  implementation_notes: "How it works / gotchas.",
  code: `/* full, standalone, copy-pasteable TSX */`,
  tailwind: "the key classes used",
  motion: {                          // optional, if animated
    library: "framer-motion",
    config: { /* ... */ },
    variants: { /* ... */ },
  },
  sources: ["aceternity", "godly"],
}

Guidelines:

1. Code must actually run. Full component with imports and a default export, valid Tailwind, correct Framer Motion / GSAP APIs. No // add animation here placeholders.
2. Tag generously — tags are weighted heavily in search.
3. Run npm run smoke (it builds + type-checks + exercises the tools) before opening a PR.
4. Keep snippets self-contained (inline SVGs over icon deps; scoped <style> for keyframes).

---

Credits

Patterns are original implementations inspired by the craft of the design-engineering community:

• Aceternity UI
• Godly
• Mobbin
• Refero

Built on the Model Context Protocol TypeScript SDK.

License

MIT