Raven MCP Server

Raven MCP

Odin's ravens brought back knowledge of the world — Raven brings back design intelligence.

Raven is an MCP server for coding agents. Click any element in the app you have running locally and say what should change — Raven sends the agent the selector, the computed styles, and your design tokens — then audits the result for contrast, tap targets, and typography.

Raven MCP is a personal open-source project by Andrew Cunliffe. It is not endorsed by, affiliated with, or supported by Intuit Inc. or any other company referenced in its source data. See NOTICE for full attribution of upstream sources and their licenses.

What it does

Raven gives Claude access to a comprehensive design knowledge base:

• Principles — Nielsen's 10 Heuristics, all 21 Laws of UX, Gestalt principles, WCAG accessibility, typography rules, color theory, mobile UX, D4D framework, UX writing, service design, brand, color-systems (palette-size discipline), and spacing-systems (base-unit grid + scale limits)
• Patterns — Proven UI patterns for signup flows, pricing pages, navigation, dropdown/select menus, forms, landing pages, dashboards, modals, empty/error/loading states, CTAs, social proof, mobile conversion — plus content patterns (error messages, empty-state copy, notifications, form validation) and service patterns (service blueprinting, human handoff, signup-as-service, omnichannel continuity, moments of truth)
• Content systems — Voice & tone guides: Conversational Product Voice, GOV.UK, Shopify Polaris, and Atlassian
• Research — Qualitative, quantitative, and usability methods with do/don't protocols and checklists. Metrics frameworks: HEART, AARRR/Pirate, North Star Metric, conversion funnel, RICE, OKRs.
• Service design — Service blueprinting (with HTML blueprint generation — current vs. ideal state), human-handoff patterns, signup-as-service, omnichannel continuity, moments of truth / recovery, and the GOV.UK Service Standard
• Brand & visual — Logo usage (clear space, min sizes, variants, placement, restraint), gradient usage (hierarchy, palette, contrast, trend vs signature), imagery (consistency, representation, purpose), visual hierarchy, brand-as-system, and current (2026) visual-design trends
• Business — Monetization models, retention strategies, onboarding optimization, growth mechanics, and product metrics frameworks
• Tokens — Design system tokens for Stripe, Linear, and more
• Creative studio — Local-first brand profiles, asset references, character reference profiles, provider-agnostic image/video/3D/audio generation jobs, campaign plans, and transparent creative scoring. Raven does not ship media-provider credentials; set RAVEN_CREATIVE_RUNNER to route jobs to your own renderer.

Install

Local stdio (npx / from source) is the full product: 110 tools, including Grab, the pattern library, and the file-backed Taste Engine. Hosted endpoints are smaller subsets — pick one path and stick to it.

Claude Code — one command

claude mcp add raven -- npx -y raven-mcp

Prefer one Raven entry. If both a local raven and a claude.ai / remote Raven are connected, the agent sees two overlapping toolsets — disable or rename one (e.g. raven-local vs raven-cloud) so it is obvious which product you are talking to.

Manual config (Claude Desktop or team .mcp.json)

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

Cursor

Same mcp.json snippet as above (~/.cursor/mcp.json or project .cursor/mcp.json) runs the full local server (Grab + Taste). Hosted options:

• Public: "url": "https://mcp.ravenmcp.ai/api/mcp" — ~45 stateless tools; no Grab, no Taste.
• Authenticated Taste: "url": "https://mcp.ravenmcp.ai/api/mcp-user" — OAuth; Taste yes, Grab still local-only.

Codex

Add under mcp_servers in config.toml:

[mcp_servers.raven]
command = "npx"
args = ["-y", "raven-mcp"]

Codex may prompt to approve many Raven tools on first use — that is client approval policy, not a smaller Raven.

Claude Desktop — one-click extension

Prefer not to edit JSON? Download raven.mcpb and double-click it. Claude Desktop installs Raven automatically — no Node, no terminal. Package version tracks npm.

From source

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

Tools

Decision Graph

The local Decision Graph keeps three node kinds: decisions, evidence, and sources. Five edge types connect them: supersedes, scoped_alongside, supports, contradicts, and derived_from. Decision status is candidate, active, superseded, or contested; nodes are not hard-deleted.

• decision_add — add an active decision with its scope, component, rationale, and rejected alternatives.
• decision_evidence — attach quantitative or qualitative evidence to a decision.
• decision_get — return one node, its connected neighbors, and attached evidence.
• decision_list — list active, superseded, contested, or candidate decisions. Candidates are excluded unless include_candidates:true or status:"candidate" is passed.
• decision_draft — capture a decision before its rationale is confirmed.
• decision_commit — confirm a rationale and surface similar active decisions for review.
• decision_supersede — replace a decision while keeping both nodes and their lineage.
• decision_scope — narrow two active decisions so they can coexist.
• decision_history — return a supersession lineage from oldest to newest.
• ingest_transcript — store a Source node and return the extraction prompt for the calling model.
• decision_import — read local git history and matching decision documents, then return source-bound extraction prompts.
• ingest_transcript_results — turn extracted JSON into candidate decisions linked with derived_from edges.
• gap_scan — rank uncovered components, missing or thin rationales, contested decisions, and derived staleness; digest_only:true is quiet when no action is needed.

For a cold start: call decision_import → run the returned extraction prompts with a model → pass each result to ingest_transcript_results → review the candidates → call decision_commit for each decision to keep. Candidates remain available through decision_get, but default decision_list and gap_scan ignore them until commit changes their status to active.

Figma comment archives (Markdown files under figma-comments-archive/ whose first line is # Figma comments archive: <label>, with ## Thread <n> headings) are picked up by default. Their settled threads use thread-aware extraction with path#Thread <n> provenance; imported candidates still require decision_commit and are never auto-committed.

Imported provenance is checked against its Source node before evidence is attached. Git references must be a full or unique-prefix match for a commit included by that import. Document references must match the imported path, optionally followed by a line (#L12) or heading fragment. Rejected references are returned in rejected_source_refs; the candidate remains available without an evidence node.

For transcripts: call ingest_transcript → run its extraction prompt → pass the result to ingest_transcript_results → review and commit the candidates. Resolve active conflicts with decision_supersede or decision_scope, inspect lineage with decision_history, and use gap_scan for health checks.

Evidence nodes and supports / contradicts edges capture quantitative and qualitative results linked to decisions.

review_diff severity policy

review_diff is advisory by default (verdict caps at warn). Two independent, combinable opt-ins escalate matching violations to error, producing a failing CI verdict:

• fail_on — a rule allowlist. Valid rules: important, bare-hex-color, hardcoded-font-size, hardcoded-font-family, hardcoded-spacing. Start with important; add token rules once DESIGN.md tokens are mature. important findings can include intentional uses (email-client compatibility, responsive overrides), so expect to justify or restructure those hunks; token rules only fire when DESIGN.md defines tokens (checks_skipped tells you when they didn't run).
• fail_on_governed — escalates findings a recorded decision governs (lexical scope+category association, not a verified contradiction). Opt in as a team strict-mode signal.

Escalation is diff-scoped: only newly added lines can fail — existing violations don't block until a diff touches them. The applied policy is echoed back under severity_policy. Omitting both keeps the existing advisory behavior unchanged. review_diff is local-stdio only (not on the hosted remote endpoints), so wire the policy into CI via npx raven-mcp.

Archive Figma comments

Archive your Figma comment history to durable JSON/Markdown before you lose access: FIGMA_TOKEN=<pat> node scripts/figma-comments-archive.mjs --md <fileKey> The PAT needs file_comments:read. Add --resolve-nodes for best-effort node names; it also needs file_content:read, and archival still succeeds if resolution is unavailable.

Without credentials: in Figma, first show resolved comments and clear any comment filters (hidden threads won't be in what you copy — and they're unrecoverable after cancellation). Figma has no bulk "copy all comments", so select and copy the thread text from the comments panel, then run (macOS): pbpaste | node scripts/figma-comments-archive.mjs --paste design-review (the last word is your archive label — any name without spaces; add --out somedir to choose the folder). Or run the command bare and paste into the terminal, ending with Ctrl-D. Separate threads with a blank line; within a thread, an author line followed by a timestamp line ("2 days ago", "Yesterday", "Mar 4, 2026") starts each comment. Paste mode writes <label>.txt (your paste, byte-verbatim — the durable record) and always renders the readable <label>.md archive. Skim the .md against your paste: message lines that themselves look like a timestamp, or blank lines inside one comment, can shift how the .md groups things — the .txt is always exact. An existing label is never overwritten; pass --force to replace it.

Click-to-change (grab) + DESIGN.md

Grab is local-stdio only. Hosted Cursor/Claude remote endpoints do not expose Grab — click-to-change needs a loopback bridge on your machine. Use local npx / Cursor local mcp.json when you need Grab.

Raven Grab connects a local page to your agent so you can click an element, describe the change, and send its selector, computed styles, matching DESIGN.md tokens, and token choices back to the session. The bridge runs on loopback and the returned script tag carries the capability key required by its routes. Computed styles are editable inline, and edits are sent to the agent as styleEdits.

Setup takes under a minute:

1. Start your local dev server.
2. Call start_grab_session with proxy_target set to the local server URL. path to a DESIGN.md is optional when proxy_target is set (Raven creates a minimal temp DESIGN.md); required when you only inject the script without a proxy.
3. Open the returned bridge URL. The overlay is already included on HTML pages served through it.
4. Click elements and enter the changes you want in the Grab panel.
5. Call get_grabbed_elements to receive the queued selections and instructions (draining frees queue capacity for later sends).

For a page you control, you can omit proxy_target and paste the returned <script> tag into the page instead.

Use read_design_md to inspect a DESIGN.md file and its flattened token index, init_design_md to create one from a stored Raven system, a blank template, or a getdesign.md starter, and update_design_md to set, rename, or remove one token without rewriting the rest of the file.

Pattern library — keep what you grab, then translate it

proxy_target also accepts a third-party URL, so you can grab from any site you are allowed to view, not just your own dev server. What you grab is otherwise gone when the tab closes, and it arrives as another site's literal values. Four tools close that loop:

• capture_reference — persist a grabbed selection under ~/.raven/references: selector, computed styles, hover/focus states, bounding rect, truncated HTML, your own note, and tags. One JSON record per capture, so grabbing the same element twice keeps both. It also renders the captured element back into a PNG beside the record, because nobody can pick a pattern out of a style map. That render is offline — every external request is aborted, so a stored reference never reaches back out to the site it came from — and it runs with scripting disabled, so a script in a captured element cannot execute. The record says so: fidelity: "offline".
• search_references — find it again later by free text, host, owner, or tags, with a per-result score and a why naming the fields that matched. Each result carries a display object holding the credit line and the image path together, so a consumer reaching for the picture carries the attribution out with it. Looking is not copying: a result reports html_available but omits the captured markup, because browsing a corpus of other people's work should not hand back their markup as a side effect of looking at it. Pass include_html: true when you actually mean to read the structure — the response then names whose markup it contains. Everything a browse is for is in the default result: the picture, the selector, the rect and the computed styles.
• map_reference_to_tokens — translate the captured literals onto your DESIGN.md tokens, so the code an agent writes uses your type ramp and palette instead of pasted values. Every binding carries the resolved value and CSS variable alongside the token name — a name alone is not something you can write into a stylesheet — and an aliased token resolves to the literal at the end of its $ref chain. Pure and deterministic: no model, no network. It reads the stored styles directly, so the whole show-it-then-translate-it path runs without the markup ever leaving Raven.
• forget_references — remove a single reference by ref_id, or every reference from a host (subdomains included). Takes the PNGs with it. Destructive and permanent, so the host sweep refuses to run without confirm: true and tells you how many records that would remove first.

How the mapping decides, because a wrong binding is worse than a stated gap:

• Colour matches on RGBA distance, not RGB — the same hex at a different opacity is a near miss, not an exact hit. Hex, rgb()/rgba() in both comma and space form, hsl(), and the CSS named colours all resolve; a syntax the matcher cannot read (oklch(), lab()) says so by name instead of reporting your palette as empty.
• Lengths normalize to px at a 16px root. Percentages and viewport units need a containing size and are returned as gaps with that reason, never converted on a guess.
• Family before proximity. A property that belongs to a token family binds inside it: padding-top takes a spacing token even when a type token is numerically closer, and line-height takes the leading token over an equally-exact size token. When no token in the right family is close enough, the result is a gap that names the cross-family near miss ("the closest token by value is space.4 (16px), but it belongs to a different family") rather than binding font-size to your spacing ramp.
• Ties break on distance, then family fit, then shortest and lexicographically-first token path, so the same inputs always produce the same binding regardless of token order.
• Broken $ref chains and cycles in your DESIGN.md come back in diagnostics even when every property still found a match — a defect in your own token file is reported, not swallowed.

Respect the source. Grab from sites you are permitted to access; the tools never bypass a paywall or a login, and owner: "third-party" is recorded on every capture.

Attribution and takedown. Every third-party record keeps the URL, host, app name and capture date it came from, and search_references derives a credit line from them on read — so the credit cannot go stale, and it travels with the picture rather than beside it. Raven claims no ownership of anything you capture.

Your corpus is local: it lives in ~/.raven/references on your own machine, and this project hosts no copy of it. So a takedown is something you run, not something you request — if a rights holder asks you to remove their material, forget_references with their host removes every record from that host and every subdomain, and the images with it:

forget_references({ host: "example.com", confirm: true })

It reports what it removed, what it could not read, and anything it tried to remove and failed — those are three different answers and it does not collapse them into one. A removal that fails part-way leaves the record in place rather than the picture, so running it again finds and finishes what was left. The confirmation prompt names the exact records it would take, and passing those ids back as expected_ref_ids pins the removal to them — anything captured in between is reported rather than swept up. If you believe this project itself is distributing your material, open an issue at https://github.com/rhinocap/raven-mcp/issues.

One boundary worth stating plainly: while the bridge is proxying a third-party site, that page is served from the bridge's own origin, so scripts on it are same-origin with the Raven overlay and can read your DESIGN.md token names and values. Raven withholds the DESIGN.md file path and every authoring route (layer moves, template and component writes, batch commits) for the duration of a proxy session, but proxy sites you would be comfortable showing your token list to.

Creative studio

Raven now covers the creative-production workflow around media generation without copying or depending on any closed vendor. The tools are orchestration primitives:

• Store brand kits locally with create_brand_profile.
• Register product photos, logos, references, or URLs with register_creative_asset.
• Create character/identity reference sets with create_character_profile.
• Generate provider-ready payloads with create_generation_job.
• Build full campaign shot lists with plan_creative_campaign.
• Score creative concepts with score_creative.

By default, jobs are saved as local draft payloads under ~/.raven/creative (override with RAVEN_CREATIVE_HOME). To run real media generation, set RAVEN_CREATIVE_RUNNER to an executable that reads one job JSON object from stdin and returns JSON on stdout. That runner can call any provider you choose; Raven never stores API keys in source.

iOS / SwiftUI audits

Raven audits native iOS apps against the Apple Human Interface Guidelines, not web/CSS conventions. None of the web-only rules (lang, title, flex-wrap, clamp, max-width, CSS custom properties, bare hex) run on iOS input — and get_checklist/get_principles take platform: "ios" to return HIG items (Dynamic Type, 44pt targets, SF Symbols, safe areas, dark-mode parity, App Review privacy) instead of the web set.

• audit_swiftui — paste SwiftUI source (source: a string or array of files). Statically flags hardcoded .font(.system(size:)) below ~13pt, tiny semantic fonts (.caption/.caption2), hardcoded Color(red:green:blue:)/hex literals (vs. asset-catalog or semantic system colors), interactive frames under 44×44pt, and ad-hoc spacing off the 4/8-pt grid. Rewards semantic Dynamic Type fonts, semantic system colors, SF Symbols, and flexible frames. Pass the optional accent_color_contents (the raw AccentColor.colorset/Contents.json) and it verifies the accent color actually defines components — catching an empty/undefined AccentColor that would silently fall back to system blue.
• audit_ios_screen — the iOS analog of audit_layout. Call with no args for the expected snapshot shape and how to capture it (Accessibility Inspector / XCUITest). Call with { elements: [{ label, rect, role, fontPt, fgColor, bgColor }], viewport } (plus an optional base64 screenshot) to score 44×44pt touch targets, contrast (with iOS secondaryLabel/tertiaryLabel treated as platform-standard — a warning, not a hard fail), and visual rhythm (alignment, gap consistency, optical balance).
• audit_ios_privacy — the "no sketchy issues" gate. Reads info_plist or an Expo app_json (managed RN apps have no Info.plist) plus optional privacy_md, entitlements, and source. Flags NS*UsageDescription strings that are vague or contradict the code (e.g. an NSHealthUpdateUsageDescription write claim that requestAuthorization(toShare: []) never fulfills), unused entitlements, Android permissions (Expo), ATS cleartext exceptions, secrets/keys shipped in the bundle or app.json extra, and default data-egress paths not disclosed at the point of choice (a pre-selected "Recommended" option that silently sends personal data to a hosted server).

All three return the same shape as audit_page — score, grade, summary, passes, errors, warnings, fix_priority (with audit_ios_screen adding a metrics block).

One command: node scripts/ios-audit.mjs <app-dir> [--snapshot snap.json] [--md report.md] discovers all the inputs and runs all three tools with an aggregated report.

React Native / Expo audits

Anyone building a React Native or Expo app gets the same treatment. RN renders to native iOS + Android widgets, so audit_ios_screen already scores its rendered output (an accessibility snapshot is platform-level); audit_rn covers the JSX/StyleSheet source — the RN analog of audit_swiftui — graded against the iOS HIG + Android Material conventions RN has to satisfy on both platforms. get_checklist/get_principles take platform: "react-native".

• audit_rn — paste RN source (source: a string or array). Flags touchables (Pressable/Touchable*) missing accessibilityLabel/accessibilityRole, touchables under 44pt with no hitSlop, allowFontScaling={false} (silently breaks Dynamic Type), fontSize below ~13, screens with no SafeAreaView/useSafeAreaInsets, and — for multi-mode apps — hardcoded colors with no useColorScheme/Appearance. Pass color_scheme: "dark"/"light" (your Expo userInterfaceStyle) and the dark-mode check is suppressed for intentionally single-mode apps. Rewards SafeAreaView, hitSlop, Platform-aware code, and a theme.
• audit_ios_privacy also accepts an Expo app_json — it audits expo.ios.infoPlist, Android permissions, plugins, and scans expo.extra/config for secrets and Google API keys.

One command: node scripts/rn-audit.mjs <app-dir> [--snapshot snap.json] [--md report.md] discovers screens + app.json (reading userInterfaceStyle so dark-only apps aren't false-flagged) and runs everything.

Responsive visibility audits

audit_responsive_visibility renders a page at multiple breakpoints (default: 390px mobile, 768px tablet, 1440px desktop, 2160px ultra-wide) and flags content elements that are visible on desktop but hidden on mobile — catching the "vanishes on mobile" bug class. Each flagged element is categorised as likely-oversight (content that shouldn't be hidden) or intentional (decorative elements). Detects hiding via CSS (hidden, display:none, opacity:0, visibility:hidden) and responsive Tailwind classes (hidden md:block, etc.).

Usage:

• audit_responsive_visibility(url) — render at default breakpoints and flag mismatches.
• audit_responsive_visibility(url, [390, 768, 1440]) — custom breakpoints.
• Optional viewportHeight (default: 900px) for tall content.

Returns flagged elements with selector, hiding class, visibility at each breakpoint, and category.

Contrast audits

audit_contrast computes WCAG contrast for every text element, reporting a tri-state status: pass, fail, or indeterminate. Determinate rows include ratio, aa, aaa, and delta_to_aa; indeterminate rows keep required_aa but publish those four metrics as null. Gradient and layered backgrounds expose effective_bg plus ratio_min / ratio_max when a trustworthy candidate range exists, and results summarize indeterminate_bg_rows / indeterminate_bg_count separately from AA failures.

Real-backdrop compositing applies to URL mode. Raven walks the rendered DOM ancestor chain, composites parseable colors and gradient layers in CSS paint order, samples gradient interiors, and normalizes modern computed colors through the browser canvas. This intentionally stops at the DOM-ancestor ceiling: opacity, display:contents, positioned transparent chains, photos, unsupported layers, and cross-stacking-context sibling backdrops are reported indeterminate; Raven does not pixel-sample across stacking contexts. Snapshot mode retains the pre-existing supplied-bgColor / over-white model and announces that scope in mode_note.

Usage:

• audit_contrast(url) — render a live page and audit all text.
• audit_contrast(dom_snapshot: [{ selector, color, bgColor, fontPx?, bold?, text? }]) — audit a pre-captured snapshot (useful for dynamic or cookie-protected pages).

Returns all text rows with status, determinate failures with delta-to-pass, effective background evidence/ranges, and separate indeterminate summaries. suggest_contrast_fix accepts only determinate failing rows; indeterminate or null-ratio evidence is skipped rather than converted into a fake color recommendation.

WCAG math: Contrast ratio uses linearised luminance (WCAG 2.1 § 1.4.3) — black-on-white is exactly 21, white-on-black is exactly 21. Large text (18.66pt+ bold or 24pt+) needs only 3:1 / 4.5:1 AAA; regular text needs 4.5:1 / 7:1.

Headless browser audits

audit_page can render a live URL in headless Chromium, scroll to settle reveal-on-scroll elements, and play preload=none videos before capturing — preventing false "blank section" reports caused by whileInView states that haven't fired yet.

Documentation truncated — see the full README on GitHub.