Raven MCP Docs

Everything you need to get Raven running with Claude Code, Claude Desktop, or any MCP-compatible client.

Get Started

Design intelligence in Claude in under 2 minutes.

Install & connect

npm install -g raven-mcp
claude mcp add raven -- npx raven-mcp

That's it. Ask Claude to build UI and Raven's tools fire automatically:

"Build me a pricing page with 3 tiers"
"Check this signup form for accessibility issues"
"Use Stripe's design tokens for the checkout flow"

No configuration needed. Once added, Claude automatically queries Raven when you ask it to build, evaluate, or improve UI. The tools fire behind the scenes.

Claude Desktop

Add to your config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "raven": {
      "command": "npx",
      "args": ["raven-mcp"]
    }
  }
}

Team config

Add a .mcp.json to your project root so everyone gets Raven automatically:

{
  "mcpServers": {
    "raven": {
      "command": "npx",
      "args": ["raven-mcp"]
    }
  }
}

Install from source

git clone https://github.com/rhinocap/raven-mcp.git
cd raven-mcp && npm install && npm run build

Tool Reference

Raven provides 13 tools across 4 knowledge layers. Claude calls them automatically based on what you're asking for.

Principles Layer

get_principles

Get design principles relevant to a UI context. Returns usability heuristics, Laws of UX, Gestalt principles, accessibility rules, typography, color theory, mobile UX, and responsive layout.

context required: What you're designing — e.g. "signup form", "pricing page", "mobile nav", "dark dashboard"
category optional: Filter to: nielsen-heuristics, laws-of-ux, gestalt, accessibility, typography, color-theory, mobile-ux, responsive-layout, d4d
format optional: "full" (default) | "checklist" | "brief"

// Claude calls this automatically when you say:
"Build a pricing page"
"What accessibility rules apply to forms?"
"Check this against Nielsen's heuristics"

evaluate_design

Evaluate a design description against UX principles. Returns relevant principles, potential violations, and improvement suggestions.

description required: Description of the design to evaluate
context optional: What the design is — e.g. "pricing page for SaaS product"
goals optional: Array of evaluation goals — e.g. ["conversion", "accessibility", "mobile-usability"]

// Try:
"This signup form has 8 fields, no social login, and the
 button says Submit. Evaluate it for conversion."

get_d4d_framework

Get Design for Delight (D4D) templates — customer problem statement, ideal state, hypothesis, LOFAs, and experiment design.

stage optional: "frame" | "empathy" | "broad" | "narrow" | "experiment" | "recommendation" | "full" (default)

Patterns Layer

get_pattern

Get proven UI/UX patterns for a specific design type. Returns do's, don'ts, evidence, and checklists.

type required: Pattern type: signup-flow, pricing-page, navigation, forms, landing-page, dashboard, modals-dialogs, empty-states, error-states, loading-states, cta, social-proof, mobile-conversion
platform optional: "desktop" | "mobile" | "responsive"
goal optional: "conversion" | "usability" | "accessibility" | "delight"

// Try:
"Show me the best patterns for a mobile signup flow"
"What does a high-converting pricing page need?"

get_checklist

Get a pre-publish checklist for a UI type. Returns actionable yes/no items to verify before shipping.

type required: What you're shipping — e.g. "signup form", "pricing page", "dashboard"
platform optional: "desktop" | "mobile" | "responsive"

// Try:
"Give me a pre-launch checklist for this landing page"
"What should I check before shipping this mobile form?"

Business Layer

get_business_strategy

Get business and monetization strategies for digital products. Covers monetization, retention, onboarding, growth, and metrics.

type required: Strategy type: monetization, retention, onboarding, growth, metrics
stage optional: "startup" | "growth" | "mature"

Tokens Layer

list_design_systems

Browse available design systems. Filter by category or search by name.

category optional: fintech, productivity, developer, component-library, design-system
search optional: Search by name or description

get_design_system

Get design tokens for a specific system. Returns colors, typography, spacing, radii, elevation, and motion tokens.

id required: Design system ID — e.g. "stripe", "linear"
group optional: Filter to: color, color-dark, color-light, typography, spacing, radius, elevation, motion
format optional: "dtcg" (W3C standard, default) | "css" (custom properties) | "flat" (key-value pairs)

// Try:
"Use Stripe's color tokens for this checkout page"
"Give me Linear's typography scale as CSS variables"

compose_system

Mix tokens from different design systems to create a custom composite.

compositions required: Array of {system, group} pairs — e.g. Linear's colors + Stripe's typography
format optional: "dtcg" (default) | "css"

// Try:
"Build me a design system with Linear's colors
 and Stripe's typography"

Search

search_knowledge

Search across all principles, patterns, and strategies. Use when you need to find specific guidance or don't know which category to look in.

query required: Search term — e.g. "touch targets", "pricing psychology", "color contrast"
layer optional: "principles" | "patterns" | "business" | "all" (default)

Advanced Tools

audit_page

Audit an HTML page against design standards. Returns a score, grade, passes, and errors with specific fix recommendations.

html required: The HTML content to audit
url optional: URL context for the page being audited
checks optional: Array of check categories: "accessibility", "mobile", "performance", "seo", "all" (default)

// Try:
"Audit this landing page HTML for accessibility and mobile issues"
"Check this signup form for WCAG compliance"

get_brand_system

Get a complete brand design system for a well-known company. Returns colors, typography, spacing, CSS variables, and implementation rules.

company required: Company name — e.g. "Stripe", "Apple", "Spotify", "Nike"
format optional: "full" (default) | "css" | "tokens"

// Try:
"Make me an app with branding like Spotify"
"Use Apple's design language for this landing page"

generate_design_system

Generate a complete, custom design system with full token set. Provide a brand color to auto-generate a harmonious palette, pick a style preset, and export as visual HTML documentation, CSS variables, W3C DTCG JSON, Figma Variables, or SVG palette card.

name required: Name for the design system — e.g. "Acme Corp", "NightOwl"
brand_color optional: Primary brand hex color (e.g. "#FF6B35") — auto-generates a full palette using color theory
base_system optional: Start from an existing system as foundation — e.g. "stripe", "linear"
style optional: "minimal" | "bold" | "warm" | "corporate" | "playful" | "dark"
dark_mode optional: Generate dark mode tokens alongside light (default: true)
format optional: "html" (visual doc page) | "css" | "dtcg" (W3C JSON) | "figma" (Figma Variables) | "svg" (palette card) | "all"

// Try:
"Generate a design system for my startup with #FF6B35 as the brand color"
"Create a bold design system called NightOwl with dark mode"
"Export my design system as Figma Variables"

Examples

You don't need to call tools directly. Just talk to Claude naturally and Raven fires automatically.

Build a pricing page with best practices

"Build me a pricing page with 3 tiers for a developer tool.
 Use Stripe's design tokens."

Raven will call get_pattern("pricing-page"), get_principles("pricing page"), and get_design_system("stripe") — then Claude builds the page using all three.

Evaluate an existing design

"This signup form has 8 fields including phone number and company
 size. No social login. The submit button says 'Submit'. No inline
 validation. Evaluate it for conversion and usability."

Raven calls evaluate_design and returns every principle being violated, with specific fixes.

Pre-launch checklist

"Give me a pre-launch checklist for this mobile landing page"

Returns a categorized checklist covering the pattern's requirements, accessibility, and platform-specific items.

Compose a custom design system

"Create a design system that uses Linear's color palette
 with Stripe's typography and spacing"

Raven calls compose_system to merge tokens from both systems into one set, output as CSS variables or W3C DTCG format.

Generate a complete design system

"Generate a bold design system for my startup called NightOwl.
 Brand color is #8B5CF6. Export as HTML so I can share it."

Raven calls generate_design_system to create a full token set — colors, typography, spacing, radius, elevation, motion — and exports it as a beautiful, self-contained HTML documentation page you can open in a browser or print to PDF.

Search across everything

"What does Raven know about color contrast?"

Searches all 73 principles, 13 patterns, and 5 business strategy domains for relevant guidance.

Data Structure

All knowledge lives in src/data/ as static JSON files. No database, no API calls, no latency.

src/data/
  principles/          # 73 principles across 10 files
    nielsen-heuristics.json   # 10 usability heuristics
    laws-of-ux.json           # 21 Laws of UX
    gestalt.json              # Gestalt principles
    accessibility.json        # WCAG & a11y rules
    typography.json           # Type scale & hierarchy
    color-theory.json         # Color systems & contrast
    mobile-ux.json            # 12 mobile UX rules (touch, nav, overflow, fonts)
    d4d.json                  # Design for Delight framework
    responsive-layout.json    # Fluid layout & intrinsic design

  patterns/            # 13 proven UI patterns
    signup-flow.json          pricing-page.json
    navigation.json           forms.json
    landing-page.json         dashboard.json
    modals-dialogs.json       empty-states.json
    error-states.json         loading-states.json
    cta.json                  social-proof.json
    mobile-conversion.json

  business/            # 5 strategy domains
    monetization.json         retention.json
    onboarding.json           growth.json
    metrics.json

  tokens/              # Design system tokens
    registry.json             # 7 systems registered
    systems/
      stripe.json             # Stripe's full token set
      linear.json             # Linear's full token set

Design Tokens

Tokens follow the W3C Design Tokens Community Group (DTCG) format. Each token has:

$value — the token value
$type — color, dimension, fontFamily, fontWeight, number, etc.
$description — what the token is for

Output formats

Request tokens in three formats:

// W3C DTCG (default) — standards-compliant JSON
get_design_system({ id: "stripe", format: "dtcg" })

// CSS Custom Properties — drop into your stylesheet
get_design_system({ id: "stripe", format: "css" })
// Output: :root { --stripe-color-primary: #635bff; ... }

// Flat — simple key-value pairs
get_design_system({ id: "stripe", format: "flat" })
// Output: [{ path: "color.primary", value: "#635bff", type: "color" }]

Available systems

System	ID	Status	Token groups
Stripe	`stripe`	Live	color, typography, spacing, radius, elevation, motion
Linear	`linear`	Live	color, typography, spacing, radius, elevation, motion
Vercel	`vercel`	Planned	—
Tailwind	`tailwind`	Planned	—
Radix	`radix`	Planned	—
shadcn/ui	`shadcn`	Planned	—
Material Design 3	`material`	Planned	—

FAQ

Does Raven make API calls?

No. All data is bundled locally in the npm package. No external API calls, no latency, no auth tokens needed. It's 272KB of curated JSON that runs on your machine.

Does it work with other AI coding tools?

Raven works with any MCP-compatible client. Claude Code and Claude Desktop have native MCP support. Other tools are adding MCP support — check your client's documentation.

Can I add my own design system tokens?

Yes. Add a JSON file to src/data/tokens/systems/ following the W3C DTCG format, and register it in registry.json. See stripe.json as a reference.

Can I add custom principles or patterns?

Yes. Add JSON files to src/data/principles/ or src/data/patterns/. Follow the existing file structure. Raven loads all JSON files in those directories automatically.

How do I update?

npm update -g raven-mcp

Where does the knowledge come from?

73 principles curated from Nielsen Norman Group, Laws of UX, Gestalt psychology, WCAG 2.1, established typography and color theory, mobile UX excellence (touch targets, nav consistency, overflow prevention, font sizing), responsive layout best practices, and component architecture (shared chrome, style encapsulation, design token contracts). 13 UI patterns based on conversion research and A/B test evidence. Design tokens extracted from public-facing design systems.