gravityui-reference-mcp

An MCP (Model Context Protocol) server providing AI-optimized access to the Gravity UI design system — 34 libraries, 1351 entities, 19 recipes. Pre-ingested data is included, so the server works offline with no setup beyond pnpm install.

Tools

The server exposes 3 tools:

find — Search by intent across all entity types. Describe what you need in plain language.

• query (required) — e.g. "date picker", "sidebar navigation", "toast notification"

• type (optional) — filter by entity type: "component", "hook", "utility", "asset", "token-set", "config-doc", "guide"

get — Deep dive into one entity, recipe, or the system overview.

• name (required) — entity name ("Button"), recipe id ("confirmation-dialog"), or "overview"

• detail (optional) — "compact" (default) or "full"

list — Browse entities with orthogonal filters.

• type (optional) — "component", "hook", "utility", "asset", "config-doc", "guide", "token-set"

• category (optional) — "actions", "ai", "data-display", "feedback", "forms", "layout", "navigation", "overlays", "typography", "utility"

• library (optional) — e.g. "uikit", "aikit", "navigation"

Related MCP server: web-ui-component-spec-mcp

Setup

pnpm install

Usage

Local setup

1. Clone and install:

   git clone https://github.com/antonskiter/gravityui-reference-mcp.git
   cd gravityui-reference-mcp
   pnpm install

2. Verify the server starts:

   pnpm serve

   Press Ctrl+C to stop. The server communicates over stdio.

With Claude Code

Register globally:

claude mcp add gravityui-docs -s user -- npx tsx /absolute/path/to/gravityui-reference-mcp/src/server/server.ts

Or per-project:

claude mcp add gravityui-docs -- npx tsx /absolute/path/to/gravityui-reference-mcp/src/server/server.ts

Verify:

claude mcp list
# gravityui-docs: ... - Connected

Use the absolute path to src/server/server.ts.

With Cursor

Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "gravityui-docs": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/gravityui-reference-mcp/src/server/server.ts"]
    }
  }
}

Restart Cursor or reload MCP servers from Settings > MCP.

Try it

Ask your AI assistant:

I need a date range picker for a booking form

It will use find to discover DatePicker, then get to retrieve props and examples.

Data Pipeline

Three-step pipeline for updating data from vendor submodules:

pnpm run update-submodules   # pull latest vendor/ sources
pnpm run extract             # per-library LLM extraction -> data/entities/*.json
pnpm run overview            # ecosystem overview + categories -> data/overview.json
pnpm run validate            # Zod schema + cross-reference checks

Data Model

All public-facing things in the ecosystem are entities with a unified schema:

• component — React components with props, examples, import statements

• hook — React hooks with signature, parameters, return type

• utility — Functions, classes, constants

• asset — Icons and illustrations

• token-set — Design tokens (spacing, breakpoints)

• config-doc — Shared configs (eslint, tsconfig, prettier)

• guide — Conceptual documentation (i18n-react, nodekit overview)

Plus recipes — hand-maintained UI patterns (confirmation dialog, dashboard layout, form validation, etc.).

Scripts

• pnpm serve — Start the MCP server (stdio, dev mode)

• pnpm build — Compile TypeScript

• pnpm test — Run tests (Vitest)

• pnpm test:watch — Watch mode

• pnpm run extract — Per-library LLM entity extraction

• pnpm run overview — Generate ecosystem overview

• pnpm run validate — Validate data with Zod schemas

• pnpm run update-submodules — Update vendor git submodules

License

MIT. Documentation in data/ is sourced from Gravity UI repositories (MIT licensed).