Skip to content
Back to search

Awwwards-mcp

Free, open-source MCP server that gives AI coding agents (Claude Code, Codex, Cursor, OpenCode, ZCode…) design inspiration from award-winning websites — search with real screenshots, pull design DNA, capture and record live sites. A Mobbin alternative. No API key.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/INSANE0777/Awwwards-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/INSANE0777/Awwwards-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/insane0777--awwwards-mcp/badge.svg)](/listings/insane0777--awwwards-mcp)

HTML

<a href="/listings/insane0777--awwwards-mcp"><img src="/api/listings/insane0777--awwwards-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**v1.0.0** — the first stable release. Any MCP-compatible coding agent can use awwwards-mcp — no API key, no account. Requires Node ≥ 22.13 (`node -v` to check). Pick your agent:

**Updates**: the server checks the npm registry once a day and prints an stderr notice when a newer `awwwards-mcp` exists (stdout stays clean for the JSON-RPC channel — your agent sees the notice as a log line). Set `AWWWARDS_AUTO_UPDATE=1` in the server's `env` to opt into background self-update; restart your agent afterwards to load it. Nothing is fetched more than once a day and serving never waits on the check.

**Claude Code**

claude mcp add awwwards -- npx -y awwwards-mcp

**Codex CLI** (ChatGPT desktop app and the IDE extension share this config)

codex mcp add awwwards -- npx -y awwwards-mcp

or in `~/.codex/config.toml` (project-scoped: `.codex/config.toml`):

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

**OpenCode** (`opencode.json` — note the command is an array)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "awwwards": {
      "type": "local",
      "command": ["npx", "-y", "awwwards-mcp"]
    }
  }
}

**ZCode** (`~/.zcode/cli/config.json` — note servers nest under `"mcp": { "servers": ... }`)

{
  "mcp": {
    "servers": {
      "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"], "env": {} }
    }
  }
}

**Claude Desktop / Cursor / Windsurf / Gemini CLI / Cline / Continue** — anything reading the common `mcpServers` JSON shape (e.g. `~/.claude/claude_desktop_config.json` or `~/.gemini/settings.json`):

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

**Anything else** — awwwards-mcp is a plain stdio MCP server: point your client at `npx -y awwwards-mcp` and it works. To pin a version, use `npx -y awwwards-mcp@1.0.0`.

**pi coding agent** has no built-in MCP by design — it uses skills and extensions instead. Two options:

1. Install the awwwards-inspiration skill (below). pi reads skills from `~/.pi/agent/skills/` or `~/.agents/skills/` (the latter is shared across agents following the Agent Skills standard). The skill teaches the workflow; for it to reach the live data, add an MCP-supporting pi extension, or run the queries in another agent and paste results. 2. Skip MCP entirely: ask pi to build you a small CLI wrapper around awwwards.com, or use a shared skills directory (`~/.agents/skills/`) so the same skill file serves pi and every other agent.

Optional full-page captures (needed by `capture_live_site`, `analyze_page_structure`, `record_site_motion`):

npm install -g playwright && npx playwright install chromium

`record_site_motion` additionally uses ffmpeg; it resolves the `ffmpeg-static` package automatically if present.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,175 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # <img src="assets/Mint-accented%20folded%20ribbon%20icon.png" alt="awwwards-mcp icon" width="32"> awwwards-mcp
  2. Free, open-source MCP server that gives AI agents design inspiration from
  3. [Awwwards](https://www.awwwards.com/) — the Mobbin-style visual reference loop,
  4. sourced from the web's best award-winning websites.
  5. [![M8ven Score](https://m8ven.ai/badge/mcp/insane0777-awwwards-mcp-1ll2az?v=2f46bb2a1c85764573ed2516bfbb1c9b)](https://m8ven.ai/mcp/insane0777-awwwards-mcp-1ll2az?s=readme) [![mcp.market](https://mcp.market/badge/insane0777-awwwards-mcp.svg)](https://mcp.market/server/insane0777-awwwards-mcp) [![Website](https://img.shields.io/badge/Website-awwwards--mcp.vercel.app-2ea44f)](https://awwwards-mcp.vercel.app) [![Sponsor](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa)](https://github.com/sponsors/INSANE0777)
  6. Project site: **https://awwwards-mcp.vercel.app**
  7. <p align="center">
  8. <picture>
  9. <source media="(prefers-color-scheme: dark)" srcset="assets/White%20awwwards-mcp%20logo%20on%20transparent.png">
  10. <img src="assets/Awwwards-mcp%20ribbon%20monogram%20with%20mint%20node.png" alt="awwwards-mcp" width="420">
  11. </picture>
  12. </p>
  13. <a href="https://github.com/INSANE0777/Awwwards-mcp"><img src="assets/demo.gif?v=2" alt="awwwards-mcp in action: search results, design DNA, motion filmstrip, band map — real tool output" width="480"></a>
  14. Your agent searches in natural language ("dark 3D portfolio sites", "soft pastel
  15. e-commerce"), sees **real screenshots inline**, and pulls the **design DNA** of any
  16. site: color palette, tech stack, design elements, award history. Then it goes past
  17. inspiration: point it at **any link** and it band-maps the page, censuses scroll and
  18. hover motion (keyframes, measured scrub curves), fingerprints the framework, captures
  19. canvas pose grids, and reads the site's bundles when a mechanism is unclear. From that
  20. evidence it **recreates the page section by section**, then converts the build into a
  21. runnable **Vite, Astro or Next.js project** with a measured motion manifest and
  22. per-section hooks. Close the loop with **`verify_build`** (band + motion scoring,
  23. measured perf) and generate GSAP timelines from the captured motion.
  24. And it's not just Awwwards websites — every capture, census, and verification
  25. tool **runs on any URL**. Just give it any site link and tell it to recreate:
  26. band-map it, study its motion, rebuild section by section, and score your
  27. build against the original.
  28. Free-text queries run on a porter-stemmed, prefix-matching FTS5 index with BM25
  29. ranking — "magazines" now finds Magazine-tagged sites (68 on the live index),
  30. best matches first, where the old substring path returned zero. Multi-word
  31. queries keep AND semantics: every token must hit the same site.
  32. ## Tools
  33. | Tool | What it does |
  34. |------|--------------|
  35. | `search_sites` | Search by color, tags, technology, award type or free-text query; e.g. `award: "soty"`, `award: "nominees"`, `award: "ecommerce"` (winners), or a technology alias like `technology: "nextjs"` which canonicalizes to the live slug. Multi-word queries match against the local FTS5 index and rank BM25 (title hits lead); zero results come with loose-match and taxonomy-tag hints. Default full results include each site's screenshot; use `responseMode: "compact"` for concise cards and inline previews of only the first two results on the requested page. |
  36. | `get_site_details` | Design DNA for one site: palette, technologies, elements, awards, description. Batch (`slugs`, up to 10) is compact enrichment for a shortlist — `compactSiteDetails` per slug (lists as counts, ≤500-char description, awards), cached/fetched/error status, no inline images. |
  37. | `compare_sites` | Compare 2–3 sites' design DNA and jury scores as text-only JSON. Uses cached details or fetches missing detail pages. |
  38. | `create_design_brief` | Turn 2–5 selected site slugs plus a required project goal into a deterministic, cited build brief. Uses cached detail/element evidence and cached Motion DNA first, fetches only missing details, returns Markdown plus versioned JSON, and runs browser band analysis only with `includeStructure: true`. |
  39. | `get_index_status` | Read local index count, crawl progress, last success/error, lock state and freshness without network requests. |
  40. | `get_index_stats` | Aggregate metrics over the **local cache only** (zero network). **All-time:** site count, gallery element count (`elements.total`) and technology/tag frequency (`items[].tag`); `elements.corpus` discloses the whole locally cached element set — total, gallery, site, categorized/uncategorized, builtWithKnown and oldest/newest fetch timestamps (aggregates only, no titles or slugs). **Windowed** by `windowDays` (default 90, 1–3650): cached details, palette colour frequency and jury score stats (n/avg/median) from at most the 500 most recently fetched detail rows, plus Motion DNA library frequency. Coverage is labelled `"locally cached subset"` on every metric; `windowDays`/`detailsCached`/`detailParseCap` appear only on the windowed metrics, while sites/elements/technologies are explicitly all-time. `top` caps each frequency list (default 10, 1–50). Aggregates only — no site slugs or titles. Personal, non-commercial use. |
  41. | `get_site_elements` | Component-level visuals for one site: each element's poster image inline (3D models, video content, mobile layouts, microcopy…) + video URLs. |
  42. | `list_categories` | Every filter the agent can search by (200+ tags, 27 colors). A legacy cache without technology facets is refreshed on read; if that refresh fails the response sets `taxonomyStale: true` with a `taxonomyWarning`. |
  43. | `get_collections` | Browse Awwwards' curated and member collections. No slug lists collections (paginated, ~32 per page, `owner`/`ref` on every row); a slug returns one page of that collection's site cards (curated e.g. `brutalism`, or `owner/slug` for member collections; `page` works for collections too). Results expose `siteCards` separately from `items` (all collectables), so element-only collections return empty sites rather than a parser error. 7-day local cache. Personal, non-commercial inspiration use. |
  44. | `search_directory` | Browse the Awwwards directory of agencies, studios and freelancers: name, profile slug, location, website and award counts. Filters are path-based (`country`, `category`, `budget`; one per request — e.g. budget `over_hundred_thousand`). Country must be canonical and case-sensitive (`United States`, not `united states`). Results carry `applied`/`ignored` filter arrays; free-text `query` is matched client-side over the one fetched page. Contact details are stripped. 7-day local cache. Personal, non-commercial inspiration use. |
  45. | `get_annual_categories` | Official Annual Awards categories (Site of the Year, Agency of the Year, …) with nominee counts from Awwwards' public read-only API. Nominee details hydrate on request. Personal, non-commercial inspiration use; media URLs are reference-only. |
  46. | `get_annual_nominees` | Nominees in one Annual Awards category, hydrated on demand at 1 request/second (default 10, max 20). Site summaries include `siteSlug` and `inLocalIndex` so agents can jump to `get_site_details` when the daily index has the site. |
  47. | `get_annual_nominee` | One Annual Awards nominee in full — site: date, description, designBy, country, images/videos; agency: location, avatar, award tag counts, featured projects. Accepts a UUID, a full `/api/annual/nominees/...` path, or category+slug; the slug form may hydrate up to 20 uncached nominees at 1 req/s (~20s worst case), so prefer an id when known. Media URLs are reference-only (`mediaNote: "reference-only"`); nothing is downloaded. |
  48. | `capture_live_site` | Optional: fresh full-page screenshot of any live URL. Waits for `load` + a settle window with a pre-scroll capped at 80 × 450px steps / 8 s (step- and time-capped so a growing page cannot stall it), so heavy sites work (`waitStrategy: "networkidle"` available). After the scroll it waits up to 10 s for a full-screen fixed preloader (≥90% viewport, z-index ≥100) to clear, so the site — not its loader — is captured; `waitForOverlay: false` skips that wait. Pass `viewport: "mobile"` for the 390×844 iPhone-class render (`"desktop"` 1440×900 default). On inner-scroller pages (`body` pinned, an inner container scrolls) it returns `mode: "anchors"` — six ordered viewport screenshots down that container as JSON `anchors[].scrollTop`/`file` paths, with no inline image and no top-level `file`; `scrollCapture: "viewport"` forces one explicit viewport shot instead. Document-scrolling pages keep the single full-page capture. Inline previews are capped at 2.5 MB of base64; `inline: false` keeps only the saved file. (needs [playwright](https://playwright.dev)). |
  49. | `analyze_page_structure` | Section band map of any page (live URL or local file:// build): tag, background, offset, height per band. Detects the real scroll container when the page pins `body` and scrolls an inner element (`overflow-y: auto/scroll`), reports it as `scrollRoot` (`tag#id.class`), and measures every band and landmark in that scroller's coordinates; the pre-scroll drives the same container. Compare a reference site's structure against your build. Same heavy-site-friendly wait (`waitStrategy: "networkidle"` available); `viewport: "mobile"` analyzes the phone-class layout (`"desktop"` default). `compare: "mobile"` adds a second 390×844 capture and returns `mobileBands` + `diff: {heightDelta, bandsAdded, bandsRemoved, reordered}` (label-matched); if the mobile capture fails you still get the desktop result plus `mobileError`. Absent, the response is unchanged. `cdpEndpoint` instead attaches to a browser you started (loopback only, requires `AWWWARDS_MCP_ATTACH=1`) and scans the already-open matching page — it never navigates, scrolls, clicks or creates tabs, and disconnects without closing yours. (needs [playwright](https://playwright.dev)). |
  50. | `record_site_motion` | Optional: short motion-through video of a live URL — preloader, scroll-triggered and hover/cursor animations. Returns an inline filmstrip JPEG plus the saved .webm path. `viewport: "mobile"` records at phone size — the filmstrip renders at the selected viewport, no pillarboxing (`"desktop"` default). Every recording also produces a **Motion Evidence Sheet** (`sheet.html` + `motion-sheet.md`): census-directed keyframes, consecutive-frame diff masks, an onion-skin composite, a cursor-trail overlay and a phase timeline — motion video turned into a document a model can actually read. Degrades gracefully: recording never fails because the sheet does. (needs [playwright](https://playwright.dev) + ffmpeg-static). |
  51. | `search_elements` | Search the element corpus (footer, hero, pricing, 404…) by free text: cached `source:"gallery"` records plus `source:"site"` records backfilled from new winners' own Elements sections; ranks BM25 over title/author/category. `category` (exact) and `stack` (case-insensitive substring, all terms AND) are applied across the whole cached corpus before the limit. It does **not** crawl the robots-disallowed `/elements/*` gallery. |
  52. | `get_element` | One element record: title, category, author, built-with stack, related elements and its media URL (image or video) pointing at awwwards' CDN. |
  53. | `get_motion_dna` | Runtime motion fingerprint of a live URL: animation libraries, render engines, ScrollTrigger stats (trigger count, scrub ratio), tween easing/duration vocab and the scroll model. Fresh capture or cached capture with timestamp. |
  54. | `analyze_scroll_map` | Per-element scroll-motion census of any URL: selector path, trigger source (gsap-scrolltrigger / native css scroll & view timelines / data-attr / css-keyframe / SMIL), animated props, duration, easing, scrub/pin flags and SVG stroke draw-ins — the rebuild recipe an agent can wire straight into GSAP timelines. Optional `scrubProbe` re-drives the page through ≤8 scroll steps and samples each scrubbed trigger's real progress curve (`scrubCurves`); every payload ends with a `choreography` block — `hints[]` (selector/value/source) and `groups` read from `gsapTriggers` tween vars and stepped sibling `delayMs`. (needs [playwright](https://playwright.dev)). |
  55. | `analyze_hover_census` | Hover-interaction census: extracts `:hover` rules from stylesheets, then samples up to 20 interactive elements before/after hover — transform/color/filter diffs plus transition timing (ms + easing). The hover recipe for rebuilds, no video required. (needs [playwright](https://playwright.dev)). |
  56. | `analyze_bundle` | Bundle forensics for a live page: fetches the page once, downloads its script chunks (script tags, inline scripts, and modulepreload/preload-as-script hints; bounded: ≤40 chunks / 10MB / 1 request/second), saves + hashes them locally, optionally de-obfuscates with webcrack if installed, and greps keywords across the code — chunk paths + match lines so an agent can read the actual animation mechanism instead of guessing. Optional `edges` adds the static import graph over the captured chunks (import/reexport declarations up to 8 KB each). Needs no browser. |
  57. | `analyze_network_capture` | Offline API-surface evidence from a local HAR 1.2 file (a browser DevTools export): requests grouped by method + origin + path template (dates, versions, UUIDs, hex ids and numbers templated; emails, tokens and long high-entropy segments redacted), with counts, statuses, content types and query names only. Reads the file only - never fetches recorded URLs and never returns bodies, headers or query values. 20 MB / 2000-entry caps; `evidenceCoverage` discloses what was excluded. No network. |
  58. | `audit_url` | Runtime + static performance **evidence** for any live URL — never a grade. Runtime: installed Chrome/Edge over raw CDP (no playwright) measures fps, dropped frames, long tasks/animations and layout thrash (`perf: {error}` when no browser exists). Static: fetches the page HTML + up to 8 same-origin CSS/JS assets (≤2MB each, one shared 1 req/s limiter, 10s default timeouts), resolving refs against the final post-redirect page URL; asset redirects leaving that origin are rejected. Scans them for animation anti-patterns and returns severity-sorted findings (`count`, `worst`, ≤50 `findings`, `coverage: {assetsScanned, failed}`) so `worst` is always included. Each half degrades independently. Personal, non-commercial use; audit only URLs you are authorised to inspect. |
  59. | `analyze_accessibility` | Accessibility **evidence** from a live page — explicitly not a WCAG pass/fail. Samples up to `limit` (default 100, max 200) visible text nodes with computed colour and a background **composited bottom-up from the ancestor stack** for fully opaque chains (colour alpha layers; reported as final `rgb()`), then the contrast ratio (worst pairs + selector paths). A sample under any ancestor CSS opacity group (<1) is **excluded from ratios** and counted in `coverage.skippedOpacityGroups` — never approximated. Background images, gradients and pseudo-elements are not composited either, so contrast stays heuristic there. Also: image alt coverage; heading ladder issues; focusable/positive-tabindex counts plus `outline:none` stylesheet rules; unlabeled form controls; document `lang`/title. Returns `coverage`, `heuristic: true` and the note "Evidence only — not a WCAG pass/fail". Accepts http(s) URLs only; degrades to `{error}` when playwright is missing. (needs [playwright](https://playwright.dev)). |
  60. | `build_project` | Convert a single-file exact rebuild (any local `.html`, e.g. the rebuild flow's `full-page-exact.html`) into a runnable **Vite**, **Astro** or **Next.js** project: sections become components, CSS splits per section, gsap timelines re-wire in the framework idiom (`useEffect` + `gsap.context` on Next), assets carried. Reads a local file and writes the project dir — the suite's one local-write tool. |
  61. | `verify_build` | Score a build against a reference site: band-map compare (Dice score) + motion-fingerprint diff (trigger mix, scrub/pin, easing vocabulary, native scroll timelines) → 0–100 score, pass/warn/fail verdict and evidence lines. `bands` carries one aggregate score plus `matched`/`refOnly`/`buildOnly` labels and a `diagnostics` row per band (reference/build index, match reason, relative-order flag, height delta, background change) — there are no per-band scores. The design-loop gate: build → verify the aggregate band score → fix → re-verify. Optional `domDiff` adds a body-subtree structural diff (missing/extra/reordered/rect drift) between reference and build. Optional `scene3d` adds a separate, opt-in 3D gate that preflights both URLs through one shared DNS/private-IP guard before any legacy scan (a private or loopback URL is refused with no requests, and the legacy acquisitions run behind the same proxy), then replays a `capture_scene_3d` pack on the build canvas and returns its own status/verdict; the legacy verdict never certifies a canvas (see [Opt-in 3D verify gate](#opt-in-3d-verify-gate-stable)). (needs [playwright](https://playwright.dev)). |
  62. | `verify_flow` | Step-aligned interaction-flow comparison: runs the same 1–6 scroll/click/wait steps on a build and a reference URL (two fresh headless launches, desktop or mobile) and compares path, scroll delta, skeleton hash, text hash and element count after each step. `same` only when both sides are complete and untruncated — truncated or failed states are `unknown`. No screenshots; a click can still trigger client-side mutations. (needs [playwright](https://playwright.dev)). |
  63. | `capture_component` | Optional: serialize one page component (CSS selector, default `header`) into a portable `component-pack-v1` JSON pack — bounded DOM tree with computed-style tokens (44 keys incl. layout offsets + `::before`/::after pseudo styles, `maxNodes` up to 2000, optional `maxDepth` where values above 12 can exceed Code Mode's depth cap and 12 keeps a capped pack safe), fonts, colors and element animations — for pixel-informed rebuilds. Adds `typography` usage summaries (families/sizes/weights/line-heights/letter-spacings, top 12 each, `sampled` node count) and a deduped `paletteSummary` (colour counts from node styles + pack colors, transparent/rgba(0,0,0,0)/none filtered, top 24). `compact: true` trades detail for tokens: each node keeps only `{tag, classes, rect}` (styles, text, svg, pseudo styles and anims are dropped) plus top-level `fonts`/`colors`; the `typography`/`paletteSummary` summaries are full-mode only. Runs on any URL. (needs [playwright](https://playwright.dev)). |
  64. | `export_design_tokens` | Deterministic design-token export from one computed-style capture: colors, typography, spacing, radii, shadows and borders as ordinal CSS variables (`--color-1`, `--space-1`, …) plus a Tailwind theme map. `selector` defaults to `body`, `maxNodes` to 800 (50–2000); `include` filters categories. Names are ordinals — never semantic guesses — values are deduped, frequency-ranked and capped; a category cap or node truncation sets `truncated` and names the reason in `notes`, and the CSS contains no URLs. Runs on any URL. (needs [playwright](https://playwright.dev)). |
  65. | `analyze_images` | Image-delivery **evidence** for a live page: totals by format, `loading` split (lazy/eager/missing), `srcset`/`sizes` coverage, intrinsic vs rendered dimensions (oversized, tiny, zero-rect), broken images and alt coverage; up to 20 issue samples with origin+pathname only (query/hash stripped, data URIs reduced to `data:<mime>`). The page loads its own assets — no tool-initiated fetches, no downloads. `maxImages` defaults to 200 (max 500); `truncated` when the pre-cap total is larger. Not a WCAG grade. (needs [playwright](https://playwright.dev)). |
  66. | `capture_pose_3d` | Hero canvas reference frames → `pose-grid-v1`; runs on any URL. Samples the page's largest canvas at up to 10 scroll steps with per-step scroll ratios (`viewport: "mobile"` supported). Frame evidence only — camera transforms are not recovered. (needs [playwright](https://playwright.dev)). |
  67. | `capture_scene_3d` | Two strict ops. `op:"capture"` writes a `scene-evidence-v1` pack for a WebGL/canvas page: up to 10 checkpoints (scroll ratio + optional normalized pointer + settle wait), each saving a viewport screenshot and a clipped canvas screenshot (the chosen canvas gets a per-run random marker; duplicate or pre-marked decoys are refused) with requested/actual scroll, scroll range, canvas CSS rect/backing size/DPR and elapsed ms plus a post-screenshot `stable`/`stabilityReason` flag; plus passive framework hints and a redacted inventory of up to 200 of the page's own responses (origin+pathname only, MIME, Content-Length when declared, resource type, texture/model/HDR/shader/script/font/image classification, plus an `assetId` and download status per row). The internal download URL is stored only when the observed URL has no query, fragment or credentials; every other row carries a skip reason. Without adapters, no hooks and no `getContext` are used during capture; the spector adapter injects its own WebGL bundle before load. `op:"download_assets"` fetches up to 32 `assetId`s from one `captureId`: `rights.basis` (`owned`/`licensed`/`permission`) and `rights.evidence` are mandatory because downloading is a licensing decision, are recorded with a timestamp in `provenance.json`, and are not verified by the server. Originals are written to `<cache>/scene-captures/<captureId>/assets` with SHA-256 and an extension validated from MIME/magic (unknown types are skipped unless `allowUnknown` saves them as `.bin`). Caps: 16 MiB/file, 64 MiB/run, 5 manual redirects, 1 request/second, 15s body deadline, 120s overall; every hop is DNS-validated and loopback/private/metadata/reserved addresses are refused. It never crawls, never guesses model or source-map URLs and never uses credentials. **Honest scope:** passive capture (no adapter) recovers no scene graph, camera, controls, shader source or geometry — frames show rendered output only. Two experimental opt-in adapters extend the pack: `adapters:["three"]` adds a bounded `evidence.three` summary from reachable globals (see [Opt-in Three adapter](#opt-in-three-adapter)), and `adapters:["spector"]` captures one WebGL frame into a bounded `evidence.spector` summary with command names/counts, context attributes and capped shader source (see [Opt-in Spector adapter](#opt-in-spector-adapter)). Neither adapter crawls the heap; a requested adapter that finds nothing leaves its capabilities unknown, not available. Capture evidence is written to `<captureId>/evidence.json` + PNG frames (metadata ≤2 MiB, 8 MiB per image, 32 MiB total); responses are compact JSON with paths, hashes, counts, coverage and limitations, never inline bodies. (capture needs [playwright](https://playwright.dev)). |
  68. | `build_pose_stub` | Pose grid → offline three.js+GSAP replay skeleton. Renders a `pose-grid-v1` grid as a standalone scroll-scrubbed stub page: frames preloaded inline (same-index loads are deduped and stale decodes discarded), a synthesized camera path interpolated between snapshot scroll ratios (guidance, not recovered camera data), reduced-motion static fallback; optional `analyze_scroll_map` census adds st/pin/ease suggestions. Pure build — no page fetches. |
  69. | `analyze_stack` | Fingerprint any page's stack from one polite HTML fetch (no browser): framework (Next.js/Astro/Nuxt/Remix/SvelteKit/WordPress/Webflow/Framer), CSS framework (Tailwind/Bootstrap) with marker lists and honest confidence, plus a `stack-fingerprint-v1` payload. |
  70. | `build_gsap_stub` | Captured motion evidence → runnable single-file GSAP+ScrollTrigger stub: one timeline per scroll-census anim (trigger, `start: "top 80%"`, scrub/pin, census duration, cubic-bezier easing normalized to the nearest GSAP token), plus an optional scroll-driven camera module from pose-grid anchors (synthesized dolly-in over the page's three.js canvas). Always-on `prefers-reduced-motion` guard; requires the full census shape (`anims[]` + `gsapTriggers[]`) - empty arrays still build a valid no-anim page, but a compact census is rejected. Pure build from provided JSON - no page fetches. |
  71. | `build_motion_manifest` | Build a `motion.manifest.json` scaffold from measured evidence: an `analyze_page_structure` result (`bands`) + an `analyze_scroll_map` census, with optional `sections: [{label, selector?}]` overrides. Sections map best-effort from each band's tag plus the first `#id`/`.class` token in its label (or the override selector); no markup is available, so DOM initial-state hints are empty while census triggers still attribute by those tokens. Returns `{manifest, measured: false, censusAnims, warnings, note}` (`manifest.measured` stays false when the census has no anims/triggers/curves); never throws (`{error}` on invalid input). Pure/offline — no page fetches. |
  72. | `build_scene_stub` | Offline Vite + Three.js scaffold from a `capture_scene_3d` pack (full profile only). Reads one `scene-evidence-v1` file (regular file ≤2 MiB, inside `scene-captures` or an exported pack with top-level `"exported": true`) and up to 32 `assetBindings` (`resourceId` → a local file you already hold: regular, non-symlink, ≤64 MiB, glb/gltf/bin/png/jpg/jpeg/webp/ktx2/hdr/exr; traversal and duplicate ids rejected). Returns `files[{path,content}]` — `package.json` with pinned `three` 0.160.0 + vite and dev/build/preview scripts, `index.html`, `src/main.js` (resize, reduced-motion static render, `GLTFLoader` for a bound model, texture loading, adapter meshes for supported Box/Plane/Sphere/Cylinder geometry with standard/basic materials, a labelled placeholder plane when no model or supported mesh exists, pagehide disposal, load-failure message), `scene.json` (bindings + frame basenames extracted from Windows or POSIX paths) and a provenance README — plus `assetCopies` to `public/assets/<assetId>.<ext>`, `unresolved`, `authoredDefaults` and `mode` (`reconstructed-subset` with a glb/gltf model or at least one supported adapter mesh, else `placeholder`). Adapter packs rebuild only the supported subset: primitive geometry, standard/basic materials and a validated perspective camera from its exact matrix (static, no idle orbit); captured controls are never recreated and are listed in `unresolved`. Unsupported geometry, materials and cameras plus missing dimensions are also listed, captured lights are recorded but not applied, and shader source/`userData` are never used. Deterministic and offline: no fetch, install, directory write or captured-code execution; copy the assets and run `npm install && npm run build` yourself. |
  73. | `search_motion` | Search previously captured motion-DNA scans by library, scroll model or easing vocabulary — find references by how a site moves. |
  74. | `new_winners` | Poll today's freshly-crowned winners (SOTD / Developer Award / Honorable Mention) against a persisted baseline. First call seeds the baseline and reports the current listing count (no element backfill); later calls report the delta. Each winner first reported after the baseline poll is backfilled into the searchable element corpus from its site page when reachable; failed per-winner fetches are not retried. |
  75. | `watch_site` | Persistent watches over studios, tags or specific sites (add/list/remove). `list` matches each watch against the freshest cached listing and reports per-watch `NEW since last check` deltas — it never fetches; `new_winners`/`search_sites` keep the pool fresh. |
  76. ### Routing
  77. | You want | Use |
  78. |----------|-----|
  79. | Sites matching filters or free text | `search_sites` — the site index with filters. |
  80. | Curated inspiration boards | `get_collections` — curated moodboards, not a search index. |
  81. | Agencies, studios or freelancers | `search_directory` — agencies/studios, not sites. |
  82. | Annual Awards categories, nominees or one nominee | `get_annual_*` — Annual Awards only. |
  83. | Design DNA for one site, or compact enrichment for a shortlist | `get_site_details` — one `slug`, or a bounded batch of `slugs`. |
  84. | Performance evidence for one URL | `audit_url` — one URL, no reference. |
  85. | A scored build-vs-reference comparison | `verify_build` — two URLs, scored comparison. |
  86. | Accessibility evidence for a live page | `analyze_accessibility` — evidence census, not compliance. |
  87. | Section bands and desktop↔mobile changes | `analyze_page_structure` — band map and responsive comparison, not a score. |
  88. | API calls a page makes | `analyze_network_capture` — offline HAR evidence, not a live network tool. |
  89. | Did my build keep an interaction flow? | `verify_flow` — step-aligned state comparison, not a visual score. |
  90. `compact:true` is the summary mode for heavy tools — `audit_url`,
  91. `verify_build`, `analyze_scroll_map`, `analyze_hover_census` and
  92. `capture_component` return a summary payload with less detail, and each shape
  93. differs: the scroll/hover censuses reduce to counts, `capture_component` drops
  94. per-node styles/text/svg/anims (the tag/classes/rect tree, fonts and colors
  95. stay; typography/palette summaries are full-mode only), and `verify_build`
  96. keeps `verdict`,
  97. `overall`, `bands` and `motion` top-level while dropping `buildUrl`,
  98. `referenceUrl` and `evidence` (`bands` holds counts); a requested `scene3d`
  99. block is kept whole because it carries its own verdict. `audit_url` keeps its
  100. top-level keys but reduces `perf` and `antiPatterns`.
  101. Batch detail is `get_site_details { slugs }`, capped at 10: results stay in
  102. input order, carry compact details only (no images), and report per-slug
  103. `cached`/`fetched`/`error`/`skipped` status. `analyze_page_structure` with
  104. `compare: "mobile"` returns responsive evidence alongside `mobileBands`/`diff`
  105. — page overflow, small text and small tap targets at 390×844 — evidence, not a
  106. score.
  107. Passive `capture_scene_3d` capture and `op:"download_assets"` are stable
  108. features. The `verify_build.scene3d` gate is stable and opt-in. The Three.js
  109. and Spector adapters remain experimental and opt-in.
  110. ### Opt-in Three adapter
  111. `capture_scene_3d` can add an experimental, opt-in Three.js adapter to an
  112. `op:"capture"` request:
  113. ```json
  114. { "request": { "op": "capture", "url": "https://example.com", "adapters": ["three"] } }
  115. ```
  116. v2 uses the same field inside the scene branch:
  117. `capture_page {request:{kind:"scene", op:"capture", url, adapters:["three"]}}`.
  118. The adapter reads only objects reachable after load from `window.THREE`,
  119. `window.scene`/`camera`/`renderer`/`controls`, and
  120. `window.app`/`experience`/`viewer`/`world` (including those holders'
  121. `scene`/`camera`/`renderer`/`controls` fields). It installs no hooks, makes no
  122. network requests and never crawls the heap. A scene held only in a module
  123. closure is invisible, so absence is not evidence of absence.
  124. The pack gains `evidence.three` (`three-adapter-v1`) only when the adapter was
  125. requested: `available`, `reason`, `revision`, `scene.nodes` (≤500 nodes, depth
  126. 20, with `truncated` and `total`), `camera` plus `cameras` (≤8), `lights` (≤8),
  127. `controls`, and `coverage` for scene, geometry, camera, controls, lights and
  128. materials. Nodes carry type,
  129. name, uuid, visibility, parent-relative position/quaternion/scale, child count,
  130. geometry (type, attributes, index count, bounds and numeric constructor
  131. parameters), and material/camera/light records. Materials are capped at 32 and
  132. texture references at 200; texture URLs are redacted to origin+pathname, and a
  133. material's `map` also carries the inventory `assetId` when the URL matches a
  134. resource row. `coverage` reflects what was actually observed: a requested
  135. adapter that finds nothing leaves capabilities `unknown`, not `available`.
  136. `build_scene_stub` reconstructs the supported subset from `evidence.three`:
  137. - Meshes only for Box, Plane, Sphere and Cylinder geometry, using captured
  138. numeric dimensions where present. A missing or out-of-range dimension falls
  139. back to an authored `1` and is listed in `unresolved`; other geometry types
  140. are skipped and listed.
  141. - Materials only as `MeshStandardMaterial` or `MeshBasicMaterial`. Other types
  142. fall back to standard and are listed; a multi-material mesh keeps only its
  143. first material.
  144. - A captured `PerspectiveCamera` is applied from its exact `matrixWorld` only
  145. when `fov`/`near`/`far` and an affine matrix validate; otherwise the authored
  146. camera stays and the gap is listed. The captured camera is static — no idle
  147. orbit — with `matrixAutoUpdate` and `matrixWorldAutoUpdate` off. Controls are
  148. never recreated: OrbitControls is not wired, because its TRS update can move a
  149. sheared or non-orthogonal pose, so any captured controls are listed in
  150. `unresolved`. With no captured camera, the scaffold keeps the authored camera;
  151. the idle orbit is used only when the pack has no usable adapter scene.
  152. - Captured lights are recorded but not applied; lighting and background stay
  153. authored defaults. The scaffold never reads or executes captured shader source
  154. or `userData`.
  155. - `mode` is `reconstructed-subset` for a model binding or at least one supported
  156. adapter mesh; otherwise `placeholder`. Textures bind only through
  157. `assetBindings`: without a local image bound to the texture's `assetId`, the
  158. material keeps its flat colour and the gap is listed.
  159. Honest limits: module-local scenes are invisible; captured node transforms are
  160. parent-relative and the stub flattens meshes at the scene root, so parent
  161. transforms are lost; texture binding is local-only; and missing nodes are not
  162. evidence of absence.
  163. ### Opt-in Spector adapter
  164. `capture_scene_3d` also accepts `"spector"` in the same `adapters` array. An
  165. `op:"capture"` request may use it alone or with `"three"` (at most two entries,
  166. no duplicates):
  167. ```json
  168. { "request": { "op": "capture", "url": "https://example.com", "adapters": ["spector"] } }
  169. ```
  170. v2 uses the same field inside the scene branch:
  171. `capture_page {request:{kind:"scene", op:"capture", url, adapters:["spector"]}}`.
  172. `spectorjs@0.9.33` is an optional dependency. When it is installed, its local
  173. `dist/spector.bundle.js` (about 1.19 MB) is read from disk and injected as an
  174. init script before navigation, so its WebGL spies exist before the page creates
  175. a context. The bundle is never fetched over the network, its UI is not shown,
  176. and worker contexts are not captured. When the package is absent, the adapter
  177. is recorded as unavailable with the install hint
  178. `npm install --save-optional spectorjs@0.9.33`; the rest of the capture still
  179. runs. A probe timeout or error likewise degrades only the adapter and never
  180. fails the scene pack. The bundle is injected once per capture that requests it.
  181. `evidence.spector` (`spector-adapter-v1`) records a compact summary of one
  182. captured WebGL frame:
  183. - `context`: WebGL version and up to 16 context attributes.
  184. - `commands`: total, draw-call count, up to 30 command names by frequency, and
  185. status counts (`unknown`, `unused`, `disabled`, `redundant`, `valid`,
  186. `deprecated`).
  187. - up to 8 programs, each with `LINK_STATUS`, `VALIDATE_STATUS`, an info log, and
  188. shader source; up to 16 shaders total.
  189. - shader source is capped at 64 Ki characters per shader and 256 Ki characters
  190. total, with `length` and `truncated` preserving the original size.
  191. - up to 8 analyses (8 keys each), canvas dimensions, adapter `limits` and
  192. truncation flags.
  193. - no command arguments, command results, GL state, stack traces, memory or raw
  194. capture is transferred into Node.
  195. Shader source is untrusted page text: it is bounded, stored as data and never
  196. executed. `coverage.capabilities.shaders` is `available` only when at least one
  197. shader source was captured; a spector request that captured none leaves it
  198. `unknown`, while capture without any adapter leaves it `unavailable`.
  199. Honest limits: one frame is captured per request. A page that has stopped
  200. drawing can yield no draw calls and therefore no programs; the adapter still
  201. returns context and command evidence with an empty `programs` array. Command
  202. arguments, results, state, stack and memory are deliberately absent, so the
  203. summary cannot explain why a draw call differs — only what was submitted.
  204. ### Opt-in 3D verify gate (stable)
  205. `verify_build` takes an optional `scene3d` block for canvas/WebGL builds. It
  206. replays the checkpoints of one `capture_scene_3d` pack against the build page in
  207. a fresh browser and compares each clipped canvas frame pixel-by-pixel.
  208. What stable means: the gate supports replaying a `scene-evidence-v1` pack,
  209. cropped canvas pixel comparison, separate status/verdict fields, diff artifacts,
  210. and a deterministic `inconclusive` on any incomparability. A verdict requires
  211. both tolerances, the same backing size and decoded frame dimensions, a
  212. replayable scroll/DPR/viewport, and one canvas with a non-empty viewport crop
  213. that carries the unique per-run marker. It does not support WebGPU,
  214. camera/geometry/shader inference, cross-viewport or image-size comparison,
  215. partial passes or scene reconstruction. Existing fields, status and verdict
  216. semantics will not change without a versioned contract or a changelog note.
  217. ```json
  218. {
  219. "buildUrl": "https://preview.example.com",
  220. "referenceUrl": "https://reference.example.com",
  221. "scene3d": {
  222. "referenceCaptureId": "scene-mg2k3j4p-0123abcd",
  223. "buildSelector": "#scene",
  224. "tolerances": { "pixelThreshold": 0.05, "maxChangedFraction": 0.02 }
  225. }
  226. }
  227. ```
  228. | Field | Meaning |
  229. |---|---|
  230. | `referenceCaptureId` | Pack id from a `capture_scene_3d` `op:"capture"` run (v2: `capture_page` `kind:"scene"`); it must match the `scene-<time>-<hex>` pattern. |
  231. | `buildSelector` | CSS selector for the build's `<canvas>`; it must match one canvas whose viewport crop is non-empty. The gate tags it with a per-run random marker and refuses duplicate or pre-marked decoys instead of guessing. |
  232. | `tolerances.pixelThreshold` | Per-channel normalized delta (0–1) above which a pixel counts as changed; default 0 while no verdict is issued. |
  233. | `tolerances.maxChangedFraction` | Maximum share of changed pixels (0–1) for the pair to stay within tolerance. |
  234. | `tolerances.cameraAngleDeg` | Accepted camera-angle delta in degrees (0–180). Only used when the reference pack carries a comparable camera angle; neither `scene-evidence-v1` nor either adapter records one. |
  235. Both `pixelThreshold` and `maxChangedFraction` are required for a
  236. `within-tolerance` or `outside-tolerance` verdict. When either is missing,
  237. comparable checkpoints still report `changedPixelFraction` and
  238. `meanAbsoluteChannelError`, but the verdict is `inconclusive`.
  239. Before any legacy structure, scroll, hover or perf scan, a requested `scene3d`
  240. creates one DNS/private-IP guard and loopback proxy and checks the reference and
  241. build URLs against it. The same proxy carries the legacy acquisitions and the
  242. anti-pattern HTML read. If either URL is not `http(s)` or resolves to a
  243. loopback, link-local, private, metadata or reserved address, the run makes zero
  244. requests and returns an unavailable report with an inconclusive `scene3d` block.
  245. `scene3d.status` (`comparable` / `inconclusive`) and `scene3d.verdict`
  246. (`within-tolerance` / `outside-tolerance` / `inconclusive`) are separate from
  247. the top-level `overall` and `verdict`. The legacy pass never certifies a canvas,
  248. and the 3D gate never changes the legacy score. `compact: true` keeps the
  249. `scene3d` block whole. A pass requires every requested checkpoint to be
  250. comparable; one blocking reason forces the whole gate to `inconclusive`, never a
  251. partial pass.
  252. Artifacts: build and diff PNGs are written under
  253. `<cache>/scene-captures/<referenceCaptureId>/verify/<run>/`; `referenceImage`
  254. points at the pack frame, and red marks changed pixels while dimmed grey marks
  255. unchanged ones. An artifact write failure is reported in `limitations` and
  256. blocks a within/outside verdict. A verify path that is a symlink/junction, or
  257. that cannot be created, makes the whole gate inconclusive; paths stay `null`
  258. when an artifact was not written.
  259. Reference stability: `capture_scene_3d` re-probes the page after each screenshot
  260. and records `stable` plus, when false, `stabilityReason`. A checkpoint with
  261. `stable: false` is rejected as inconclusive with that reason; packs without the
  262. optional `stable` field remain accepted, while the other checkpoint fields are
  263. still required. Capture cannot detect a WebGL context loss on the reference
  264. page, so reference frames carry no context-loss proof — only the build side is
  265. checked.
  266. Build-side re-probe: before the screenshot the gate requires the build to hold
  267. the reference's measured scroll position (±2 px) and to match the reference DPR
  268. and canvas backing size. After the screenshot it re-probes again and requires
  269. the position to stay within 2 px of both the pre-shot measured position and the
  270. reference `actualScrollTop`, and the canvas rect, backing size and DPR to be
  271. exactly unchanged; a WebGL context loss observed at either probe invalidates the
  272. checkpoint. The screenshot is not atomic, so a post-shot shift is an
  273. inconclusive result, not a pass.
  274. Inconclusive cases include a missing, unreadable or blank frame (≤4 sampled
  275. colours) on either side; an unstable reference frame; mismatched device pixel
  276. ratio or canvas backing size (frames are never scaled); a scroll mismatch or a
  277. post-shot shift; a missing or lost scroll root, a canvas that is missing, not a
  278. `<canvas>`, outside the viewport, or not uniquely taggable (duplicate or
  279. pre-marked decoys); WebGL context loss; the watchdog or a page
  280. load, evaluation, screenshot or comparison timeout/error; and incomplete or
  281. malformed evidence (missing pack, viewport or checkpoints, more than 10
  282. checkpoints, or a checkpoint missing its required scroll/geometry fields).
  283. The deadline is dynamic: the sum of the replayed checkpoint waits plus 10 s of
  284. acquisition/comparison headroom, floored at 15 s and capped at 45 s (the
  285. maximum schedule, 10 checkpoints x 2000 ms waits, yields 30 s). It is armed
  286. before the pack is resolved and covers every asynchronous step: pack read, DNS
  287. gate, artifact preparation, frame reads, the Playwright import/loader, browser
  288. launch, and the comparison. A timeout returns `inconclusive` with the deadline
  289. reason. Cleanup closes tracked resources
  290. concurrently under one shared 3 s grace, so the result returns within the
  291. deadline plus roughly 3 s; close promises still pending after the grace are
  292. abandoned, and their underlying teardown may linger. Resources that resolve
  293. after the deadline still get a closure attempt, but it is not awaited.
  294. The build URL must be `http(s)` and its host must resolve to a public address.
  295. Loopback, link-local, private, metadata and reserved destinations are refused;
  296. the exact-origin loopback allowance is an internal test option, not a tool
  297. input, so a build served from `localhost` is inconclusive for this gate.
  298. Camera: without an adapter, `scene-evidence-v1` records no camera state. The
  299. three adapter records a single camera pose (and a camera list), not a
  300. per-checkpoint angle; the spector adapter records none. `cameraAngleDeg`
  301. therefore stays `null` with a stated reason and a camera tolerance cannot be
  302. evaluated. That note alone does not make a measured pair incomparable.
  303. Honest limits: one frame per checkpoint — animation that shifted in time
  304. relative to the reference may land outside tolerance for reasons unrelated to
  305. fidelity; the gate compares pixels only and does not read the pack's
  306. scene/camera/geometry evidence, so it cannot attribute a mismatch; and there is
  307. no scaling, so the build must match the reference's DPR within 0.01, the same
  308. backing size and the same decoded frame dimensions.
  309. `create_design_brief` turns 2–5 shortlisted references into a cited direction:
  310. 1. Search and shortlist references with `search_sites`.
  311. 2. Call `create_design_brief` with the slugs and a required project goal.
  312. 3. Use its Markdown direction and versioned JSON; set `includeStructure: true` only when optional browser-derived section-band evidence is needed.
  313. The response separates observed shared signals from one-site outliers, names evidence gaps, and never records motion automatically. Its Interaction Plan applies only evidence-backed cursor/hover, scroll, entrance/reveal, easing, and duration cues; empty fields mean the brief has no supporting evidence, not that an effect should be invented. It also carries a `prefers-reduced-motion`, content-access, and keyboard-access guardrail.
  314. **Data posture**: element records store metadata + media URLs pointing at
  315. awwwards' own CDN — nothing is mirrored. Motion DNA records are local
  316. captures, each stamped with the time it was taken.
  317. ## Setup
  318. **Local-first, no API key, no account.** Any MCP-compatible coding agent can use awwwards-mcp. The server runs locally, but it is not zero-egress at startup: the CLI may refresh the index and check npm for updates.
  319. Requires Node ≥ 22.13 (`node -v` to check). Pick your agent:
  320. **Updates**: the server checks the npm registry once a day and prints an
  321. stderr notice when a newer `awwwards-mcp` exists (stdout stays clean for the
  322. JSON-RPC channel — your agent sees the notice as a log line). Set
  323. `AWWWARDS_AUTO_UPDATE=1` in the server's `env` to opt into background
  324. self-update; restart your agent afterwards to load it. Nothing is fetched
  325. more than once a day and serving never waits on the check.
  326. > **`npx` is the core, no-browser path.** `npx -y awwwards-mcp` runs the
  327. > package from an isolated cache that does not contain Playwright or
  328. > ffmpeg-static, so `capture_live_site`, `analyze_page_structure`,
  329. > `record_site_motion`, `verify_build` and the other browser tools return an
  330. > install hint instead of running. For those, use the
  331. > [global side-by-side install](#browser-enabled-install-side-by-side).
  332. **Claude Code**
  333. ```bash
  334. claude mcp add awwwards -- npx -y awwwards-mcp
  335. ```
  336. **Codex CLI** (ChatGPT desktop app and the IDE extension share this config)
  337. ```bash
  338. codex mcp add awwwards -- npx -y awwwards-mcp
  339. ```
  340. or in `~/.codex/config.toml` (project-scoped: `.codex/config.toml`):
  341. ```toml
  342. [mcp_servers.awwwards]
  343. command = "npx"
  344. args = ["-y", "awwwards-mcp"]
  345. ```
  346. **OpenCode** (`opencode.json` — note the command is an array)
  347. ```json
  348. {
  349. "$schema": "https://opencode.ai/config.json",
  350. "mcp": {
  351. "awwwards": {
  352. "type": "local",
  353. "command": ["npx", "-y", "awwwards-mcp"]
  354. }
  355. }
  356. }
  357. ```
  358. **ZCode** (`~/.zcode/cli/config.json` — note servers nest under `"mcp": { "servers": ... }`)
  359. ```json
  360. {
  361. "mcp": {
  362. "servers": {
  363. "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"], "env": {} }
  364. }
  365. }
  366. }
  367. ```
  368. **Claude Desktop / Cursor / Windsurf / Gemini CLI / Cline / Continue** — anything
  369. reading the common `mcpServers` JSON shape (e.g. `~/.claude/claude_desktop_config.json`
  370. or `~/.gemini/settings.json`):
  371. ```json
  372. {
  373. "mcpServers": {
  374. "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"] }
  375. }
  376. }
  377. ```
  378. **Anything else** — awwwards-mcp is a plain stdio MCP server: point your client
  379. at `npx -y awwwards-mcp` for the core tools. To pin a version, use
  380. `npx -y awwwards-mcp@1.9.0`.
  381. **pi coding agent** has no built-in MCP by design — it uses skills and
  382. extensions instead. Two options:
  383. 1. Install the awwwards-inspiration skill (below). pi reads skills from
  384. `~/.pi/agent/skills/` or `~/.agents/skills/` (the latter is shared across
  385. agents following the Agent Skills standard). The skill teaches the workflow;
  386. for it to reach the live data, add an MCP-supporting pi extension, or run
  387. the queries in another agent and paste results.
  388. 2. Skip MCP entirely: ask pi to build you a small CLI wrapper around
  389. awwwards.com, or use a shared skills directory (`~/.agents/skills/`) so the
  390. same skill file serves pi and every other agent.
  391. ### Browser-enabled install (side-by-side)
  392. Browser captures (`capture_live_site`, `analyze_page_structure`,
  393. `record_site_motion`, the scroll/hover censuses, `verify_build`,
  394. `capture_component`, `export_design_tokens`, `analyze_images`,
  395. `capture_pose_3d` and `capture_scene_3d`) need optional packages that are **not** dependencies of
  396. awwwards-mcp. The walkthrough below is the path the two checks at the end of
  397. this section cover for the install layout:
  398. 1. Install the server and those packages side by side in one global prefix:
  399. ```bash
  400. npm install -g awwwards-mcp playwright ffmpeg-static
  401. npm exec --global -- playwright install chromium
  402. ```
  403. 2. Point your MCP client at the installed `awwwards-mcp` command (not `npx`).
  404. Remove an older entry in that scope first:
  405. ```bash
  406. claude mcp remove awwwards
  407. claude mcp add awwwards -- awwwards-mcp
  408. ```
  409. ```json
  410. {
  411. "mcpServers": {
  412. "awwwards": { "command": "awwwards-mcp" }
  413. }
  414. }
  415. ```
  416. 3. **Restart the MCP server** (or the agent that hosts it). The client spawns
  417. the server process once; the new command and any `env` only take effect
  418. after a restart.
  419. 4. **Verification call** — ask the agent to run one browser tool, e.g.
  420. `analyze_page_structure` on any page:
  421. ```json
  422. { "name": "analyze_page_structure", "arguments": { "url": "https://example.com" } }
  423. ```
  424. Success is JSON with a `bands` array (at least one entry) and a
  425. `totalHeight`. A response naming the Playwright install hint means the
  426. server cannot import or launch Playwright from its own install location;
  427. redo step 1 before using any browser tool.
  428. In this layout all three packages are siblings in the same `node_modules`, so
  429. the server's bare `import("playwright")` / `import("ffmpeg-static")` resolve
  430. from its own install location; `record_site_motion` uses ffmpeg-static
  431. automatically. `npx -y awwwards-mcp` has no such siblings: core tools work,
  432. browser tools cannot. Installing only `awwwards-mcp` globally has the same
  433. limitation — Playwright and ffmpeg-static must be installed globally too.
  434. Two commands cover this walkthrough. `npm run pack:smoke` packs the tarball,
  435. installs it into a throwaway global prefix and proves the side-by-side
  436. resolution layout with stand-in Playwright/ffmpeg packages.
  437. From a clone of this repository (the smoke is a dev check, not shipped in the
  438. tarball), `npm run smoke:browser` packs and installs this checkout into a
  439. throwaway global prefix with the **real** Playwright/ffmpeg packages linked as
  440. siblings, then runs the installed server over MCP stdio against a local static
  441. fixture with real Chromium:
  442. ```bash
  443. npm run build && npm run smoke:browser
  444. ```
  445. The smoke serves a three-section page on `127.0.0.1`, seeds a throwaway cache
  446. (so no crawl or daily update check starts), then makes two real calls — one
  447. `analyze_page_structure`, one `capture_live_site` — and fails on a missing band,
  448. a non-PNG image or a timeout. Observed result (Windows, Node 24, Playwright
  449. 1.63, 2026-11-01):
  450. ```
  451. browser-smoke: pack + global install
  452. browser-smoke: connected to awwwards-mcp, 41 tools
  453. browser-smoke: analyze_page_structure -> 4 bands, totalHeight 2061, labels body,#hero.hero,#work.work,#contact.contact
  454. browser-smoke: capture_live_site -> image/png 17.5 KB inline, saved capture-38f75233f8a4-desktop.png
  455. browser-smoke: PASS
  456. ```
  457. That run predates Atlas; with `AWWWARDS_MCP_ATLAS=1` the same check reports 45 tools.
  458. `npm run qualify:installed` is the release-artifact qualification. It packs
  459. this checkout, installs the tarball into a throwaway prefix, gives every child
  460. server/CLI an isolated `HOME`/`USERPROFILE`/`APPDATA` and throwaway caches, then
  461. runs the profile surfaces (41/13/15 with the flag off, 45/13/16 with
  462. `AWWWARDS_MCP_ATLAS=1`), both protocol eras, Atlas branch schemas, annotations,
  463. CLI refusals and a real-Chromium fixture over MCP stdio. The machine-readable
  464. report goes to `.qualification/installed-report.json`.
  465. Exit 0 means every required check passed **and** browser qualification was
  466. exercised (`qualificationScope: "full"`). An offline or `--no-browser` run is
  467. `qualificationScope: "offline-installed"` and is never PASS: with no failures
  468. it is INCOMPLETE (exit 2), and real failures still exit 1. Because a positive
  469. Atlas capture needs a permitted non-loopback fixture, a fully offline machine
  470. reports INCOMPLETE even when every other check passes. For a full browser
  471. qualification, point the harness at the approved owned fixture:
  472. ```bash
  473. npm run qualify:installed -- --fixture-url https://awwwards-mcp.vercel.app/
  474. ```
  475. The URL is validated against the compiled-in approved fixture; any other URL is
  476. refused before any browser launch. The equivalent environment variable is
  477. `AWWWARDS_QUALIFY_FIXTURE_URL`. With the fixture check passing,
  478. `qualificationScope` becomes `full` and exit 0 is possible. `--skip-build` refuses a
  479. `dist` older than `src` and reports INCOMPLETE (exit 2), so an existing build
  480. cannot qualify stale code.
  481. To qualify a tarball that already exists, without rebuilding or repacking:
  482. ```bash
  483. npm run qualify:installed -- --tarball <packed.tgz> \
  484. --fixture-url https://awwwards-mcp.vercel.app/
  485. ```
  486. The tarball is hashed with its npm SHA-512 integrity, installed from that exact
  487. path, and the package name/version are read back from the installed tree. The
  488. report goes to `.qualification/installed-report.json` by default. Without
  489. `--fixture-url` the run is `qualificationScope: "offline-installed"` —
  490. INCOMPLETE (exit 2), never a release PASS. A qualifying report is then gated
  491. against the same bytes:
  492. ```bash
  493. node scripts/qualify/gate.mjs \
  494. --report .qualification/installed-report.json --tarball <packed.tgz> \
  495. --filename <tarball basename> --package awwwards-mcp --version <version>
  496. ```
  497. `--mode` defaults to `tarball`; use `--mode pack` for a report from a pack-mode
  498. qualification. Add `--integrity <registry-SRI>` when gating an already-published
  499. version. A report only qualifies the exact bytes it names; the gate must pass
  500. before the same path is published.
  501. ### Resource limits and diagnostics
  502. All optional and read at startup:
  503. | Variable | Default | Effect |
  504. |---|---|---|
  505. | `AWWWARDS_MCP_PROFILE` | `full` | `core` registers only the 13 build-loop tools (`search_sites`, `get_site_details`, `analyze_page_structure`, `analyze_scroll_map`, `capture_component`, `verify_build`, `build_project`, `get_motion_dna`, `analyze_stack`, `capture_live_site`, `get_annual_categories`, `get_annual_nominees`, `get_collections`); `full` keeps all 41 (45 with `AWWWARDS_MCP_ATLAS=1`); `v2` (beta) replaces the list with the 15-tool consolidated surface (16 with `AWWWARDS_MCP_ATLAS=1`). The old → new v2 mapping is in [awwwards-skills repository](https://github.com/INSANE0777/awwwards-skills). |
  506. | `AWWWARDS_MCP_ATLAS` | off | `1` adds the experimental Atlas tools and v2 branches; `full` = 45 and `v2` = 16, `core` stays 13. Read once at startup. See [ATLAS.md](./ATLAS.md). |
  507. | `AWWWARDS_MCP_MAX_RESPONSE_BYTES` | `32000000` | Full serialized tool-result bytes (text, inline images and `structuredContent`). Larger responses replace `content` with a `{truncated:true, tool, bytes, limit, note}` JSON block; a truncated structured payload is dropped and reported as `isError: true`. |
  508. | `AWWWARDS_MCP_DEBUG_MEMORY` | unset | `1` logs one JSON line per tool call (duration, rss, heap) to stderr - never stdout. |
  509. | `AWWWARDS_MCP_IMAGE_RETENTION_DAYS` | `0` (off) | A positive N prunes cached `images/` files older than N days once at startup. |
  510. | `AWWWARDS_MCP_IMAGE_MAX_BYTES` | `26214400` (25 MB) | Maximum size of one cached CDN image/asset download; larger responses (declared or streamed) are aborted before they are fully buffered. |
  511. The v1.14.0 `AWARDS_MCP_*` spellings (one fewer W) are still accepted as a one-release fallback; the `AWWWARDS_MCP_*` name wins when both are set.
  512. `AWWWARDS_MCP_PROFILE=v2` is the opt-in beta surface: 15 tools (16 with `AWWWARDS_MCP_ATLAS=1`), never registered alongside the 1.x names. Ten consolidate the old surface (`search_references`, `get_reference`, `browse_awards`, `get_index`, `inspect_page`, `analyze_motion`, `capture_page`, `audit_page`, `build_motion`, `monitor_awards`) and five are retained (`create_design_brief`, `build_project`, `verify_build`, `verify_flow`, `analyze_network_capture`). Each consolidated tool takes exactly one `request` branch. `monitor_awards` `add_watch`/`remove_watch` require `kind` and `pattern` at the schema boundary (the 1.x handler rejected them later; the valid set is the same). Profiles are exclusive and read once at startup - `full` = 41, `core` = 13, `v2` = 15 (45 / 13 / 16 with `AWWWARDS_MCP_ATLAS=1`) - so changing the value requires a server restart. The complete 1.x → v2 mapping for all 36 replaced names is in [awwwards-skills repository](https://github.com/INSANE0777/awwwards-skills).
  513. `capture_live_site` also accepts `inline: false` to skip the base64 preview and `maxInlineBytes` to change the budget; captures whose base64 would exceed the budget (default 2.5 MB) are saved without an inline image, decided from the raw PNG size before conversion. Inline images from `capture_pose_3d` and `capture_component` count toward the same `AWWWARDS_MCP_MAX_RESPONSE_BYTES` budget. `analyze_network_capture` reads HAR files up to 20 MB (re-checked after reading) and 2000 entries. The `analyze_bundle` import graph supports import/reexport declarations up to 8 KB each.
  514. ### Experimental Atlas tools
  515. `AWWWARDS_MCP_ATLAS=1` (read once at startup) additionally registers `search_atlas`, `get_atlas`, `capture_atlas` and `export_evidence_pack` (in the `v2` profile only the last of those) together with the v2 branches `search_references` `kind:sections|components`, `get_reference` `kind:atlas_region|atlas_highlight|atlas_taxonomy`, `get_index` `kind:atlas_status` and `capture_page` `kind:atlas`. With the flag off those tools are not registered and the historical 41 / 13 / 15 surface is unchanged; the v2 branch values stay declared by their request schemas and answer with `FEATURE_DISABLED`. Atlas search is local only; candidate labels are uncalibrated hints and `empty_corpus` / `insufficient_coverage` mean not observed, never proven absent. Capture accepts a known site slug only and returns partial evidence without publication when publication is refused; `published` always reports the actual result. Exported packs stay in the local cache: `includeMedia:"references"` copies derived summaries only, while `permitted` copies an artifact only with a caller rights assertion and never overrides robots/destination refusals. See [ATLAS.md](./ATLAS.md) for the tool table, scopes, evidence modes and rights constraints.
  516. ### Attach to your own browser
  517. `analyze_page_structure` can scan a page you already have open instead of
  518. launching its own browser. Start Chrome/Edge with a **throwaway profile** —
  519. version 136+ ignores `--remote-debugging-port` on the default profile:
  520. ```bash
  521. chrome --remote-debugging-port=9222 --user-data-dir=<throwaway dir>
  522. ```
  523. Open the exact URL in the window that starts: it runs in the throwaway profile,
  524. not your everyday one, so it carries none of your normal cookies or logins.
  525. Then set `AWWWARDS_MCP_ATTACH=1` in the server's environment (restart the
  526. server), and pass `cdpEndpoint: "http://127.0.0.1:9222"` — or
  527. `http://[::1]:9222`, or a `ws://127.0.0.1:9222/devtools/browser/<id>` endpoint.
  528. - **Loopback only.** The endpoint must be `127.0.0.1` or `[::1]`; HTTPS/WSS,
  529. credentials, queries, fragments, non-loopback hosts and extra paths are
  530. rejected. For an `http://` endpoint the server reads `/json/version` itself
  531. (5 s timeout) and refuses to connect unless the returned
  532. `webSocketDebuggerUrl` is also a loopback ws URL.
  533. - **Never navigates, scrolls, clicks or creates tabs.** The server selects the
  534. existing page whose normalized URL matches `url` exactly; if none matches it
  535. returns an error listing the open origins (never paths). It takes no
  536. screenshots and changes nothing on the page except an idempotent
  537. `globalThis.__name` helper used by dev-mode snippet runs.
  538. - **No compare.** `compare: "mobile"`, a custom `viewport` and responsive
  539. evidence are rejected in attach mode because each would drive the page.
  540. - **Disconnect only.** When the scan ends the server disconnects from CDP; your
  541. browser and tabs stay open.
  542. - **Off by default.** Without `AWWWARDS_MCP_ATTACH=1` the tool returns an error
  543. explaining the gate, so an agent cannot attach to a browser you did not offer.
  544. Keep the debugging port bound to loopback.
  545. ## Skills
  546. The nine agent skills live in the separate
  547. [awwwards-skills repository](https://github.com/INSANE0777/awwwards-skills),
  548. which is their source of truth. This package does not ship them.
  549. Install them with the [`skills` CLI](https://skills.sh):
  550. ```bash
  551. npx skills add INSANE0777/awwwards-skills
  552. ```
  553. Tested pairing: **`awwwards-mcp@1.20.0` + `skills-v2026.11.16`**. The 1.20 release
  554. keeps the same **41 / 13 / 15** tool surface (**45 / 13 / 16** with
  555. `AWWWARDS_MCP_ATLAS=1`), but rerun the
  556. compatibility check before a later release changes either side.
  557. The CLI detects your agents and lets you choose a project or user-level
  558. install, then links each skill into that agent's skills directory. Useful
  559. flags: `--skill <name>` for one skill, `-a <agent>` to target specific
  560. agents, `-g` for a user-level install, `--copy` to copy files instead of
  561. symlinking, and `-l` to list what the repository contains without
  562. installing. Any agent that reads the
  563. [Agent Skills standard](https://agentskills.io) layout can also use the
  564. `skills/<name>/` directories from that repository directly.
  565. | Skill | What it teaches |
  566. |-------|-----------------|
  567. | `awwwards-setup` | First-time onboarding: asks the user's preferences (result density, viewport, captures, local index, winner watches), persists them to `~/.awwwards-mcp/preferences.json`, and runs any one-time installs they opt into. |
  568. | `awwwards-inspiration` | The inspiration loop: search, judge from screenshots, pull design DNA, state a design direction, capture/motion-first builds; staying current with `new_winners` and `watch_site`. |
  569. | `awwwards-motion-study` | The full video chain: what to record from a live site (and what to skip), frame-by-frame review (video input or tile-per-element), the motion inventory, and build verification by re-recording. Now opens with an instrument-first pass: scroll/hover censuses, motion DNA, and pose capture before (and instead of) recording. |
  570. | `awwwards-doctor` | Repair: run `npm run doctor`, apply its fixes, re-anchor parsers after real awwwards.com drift, recover the in-flight task that surfaced the failure. |
  571. | `awwwards-section-loop` | Section-by-section rebuilding: band map → per-section capture → build → verify the aggregate band score → lock → next; selector fallback rules, shared-canvas one-unit rule, and the lock-before-next discipline. |
  572. | `recreate` | `/recreate <url>` — the full link-to-site playbook: study-build disclaimer gate → evidence capture (bands, components, censuses, motion DNA, pose, bundle) → hand build with exact assets → scroll-anchor QA gate → project conversion **only on request** (`build_project`, native structure + authored motion) → handoff. |
  573. | `motion-authoring` | `/authored` conversions: topology (master scrub vs independent triggers), manifest contract (evidence, never hand-marked measured), intent mapping, per-target surfaces (no double GSAP), and the desktop + 390 mobile parity gate. |
  574. | Agent | Skills directory |
  575. |-------|------------------|
  576. | Claude Code | `~/.claude/skills/` |
  577. | pi | `~/.pi/agent/skills/` (also reads `~/.agents/skills/`) |
  578. | ZCode | `~/.zcode/skills/` |
  579. | Agent Skills-standard agents | `~/.agents/skills/` |
  580. Each installed skill is self-contained: it carries its own `v2-routing.md`
  581. reference and, where needed, the `_memory/techniques.json` registry. Edit and
  582. test skills in the awwwards-skills repository; this MCP repository does not
  583. carry skill copies.
  584. ## Indexing (recommended)
  585. `search_sites` works out of the box, but its depth is limited by polite live
  586. scraping (~31 sites per filter page). Build a local index once and searches
  587. draw from thousands of award-winning sites instantly:
  588. ```bash
  589. npx -y -p awwwards-mcp awwwards-index # once published
  590. # or, from a local checkout of this repo:
  591. npm run index
  592. ```
  593. - Crawls all ~200 tag pages at 1 request/second (~4 minutes) into the local
  594. SQLite cache at `~/.awwwards-mcp/`.
  595. - Resumable: interrupt it and re-run — completed pages are skipped.
  596. - The MCP server re-indexes automatically in the background whenever the
  597. index is older than 7 days (never blocking your session). Completed crawl
  598. checkpoints are cleared so each refresh actually revisits the tag pages.
  599. Run `get_index_status` to inspect progress or the last crawl error.
  600. ### Elements corpus (gallery crawl retired)
  601. The `/elements/*` gallery is robots-disallowed; it has not been fetched since
  602. v1.16.0, when the gallery crawl was removed. `npm run index -- --elements`
  603. (and the published `awwwards-index --elements`) exits 2 with an explanation
  604. before any request, and `search_elements` returns an empty-corpus note instead
  605. of indexing. There is no replacement crawler.
  606. Cached gallery records from earlier versions remain searchable. New elements
  607. come from winners first reported after the baseline poll: `new_winners`
  608. backfills each one's site page Elements section as `source:"site"` records
  609. when reachable. Site-derived slugs are namespaced `site-<siteslug>-<title>`,
  610. so the two sources never collide. `get_index_stats` keeps `elements.total` as
  611. the gallery-only count and adds `elements.corpus` with the full cached split
  612. (total, gallery, site, categorized/uncategorized, builtWithKnown, oldest and
  613. newest fetch timestamps), so the gallery count is not read as the searchable
  614. set.
  615. Element rows are searched by title, author, category **and slug tokens**
  616. (slug is an FTS5-indexed column; a cache opened from an older schema version
  617. rebuilds its search index automatically on first open). Each element also
  618. carries the slug of the award-winning site it came from (`siteSlug`/`siteUrl`
  619. in `search_elements`/`get_element` results).
  620. Site details (palettes, tech stacks) are still fetched on demand and cached
  621. for 7 days. Awwwards page and CDN requests have a 10-second deadline per
  622. attempt, including response-body reading; transient page failures are retried
  623. once, while blocks (403/429) and CDN failures are not retried.
  624. ## Atlas (experimental, opt-in)
  625. Atlas is a local, section-level evidence layer over the existing SQLite cache.
  626. It is off by default and enabled with one flag, read once at startup:
  627. ```bash
  628. AWWWARDS_MCP_ATLAS=1
  629. ```
  630. | Profile | Flag off | Flag on |
  631. |---|---:|---:|
  632. | `full` (default) | 41 | 45 |
  633. | `core` | 13 | 13 |
  634. | `v2` | 15 | 16 |
  635. Flag on adds four full-profile tools: `search_atlas`, `get_atlas`,
  636. `capture_atlas` and `export_evidence_pack`. In the v2 surface the same
  637. operations are branches of existing tools (`search_references`
  638. `kind:sections|components`, `get_reference`
  639. `kind:atlas_region|atlas_highlight|atlas_taxonomy`, `get_index`
  640. `kind:atlas_status`, `capture_page` `kind:atlas`) plus the one new flat tool
  641. `export_evidence_pack`. Flag off, the four tools are not registered, the v2
  642. branches return `FEATURE_DISABLED`, and the historical 41 / 13 / 15 surface is
  643. unchanged. Atlas tables and files are additive and survive turning the flag
  644. off.
  645. Search is local only. It returns sections or components with witness claims,
  646. artifact descriptors, coverage and a cursor; it never fetches a page and never
  647. refreshes a capture. Scopes are explicit — same region, same page or same site
  648. — so traits from different regions do not silently combine. `hover` and
  649. `focus` queries read only evidence captured for that exact state.
  650. `empty_corpus` and `insufficient_coverage` mean **not observed**, never proven
  651. absent.
  652. ```json
  653. {
  654. "kind": "sections",
  655. "predicates": [
  656. { "field": "section.purpose", "values": ["pricing"] },
  657. { "field": "region.landmark", "values": ["main"] }
  658. ],
  659. "scope": "region",
  660. "viewport": "desktop"
  661. }
  662. ```
  663. Component types are the weak spot. `card`, `drawer`, `carousel`,
  664. `icon_button` and `tooltip` are inferred, **candidate-only** hints and never
  665. satisfy `accepted` or `observed_only` search. The spec's F9 gate — accepted
  666. native/declared component-type precision ≥95% against held-out human labels —
  667. is **not met**; no held-out human component labels exist yet. Search therefore
  668. defaults to `evidenceMode: "candidate"`, marks every candidate hit
  669. `candidateOnly: true`, and adds `CLASSIFICATION_AMBIGUOUS`. Pass
  670. `evidenceMode: "accepted"` for accepted labels only. Section classification is
  671. also uncalibrated (candidate precision 0.787, recall 0.147 on the held-out
  672. review), so no label is advertised as validated taxonomy.
  673. Retrieval stays local too. `get_atlas` reads `status`, `taxonomy`, one `region`
  674. or one `highlight`. A region carries capture conditions, up to 128 claims,
  675. availability-checked artifact descriptors and bounded parent/child summaries;
  676. it does **not** embed the raw component tree by default — use the pack artifact
  677. path and hash. A highlight resolves an existing element id through stored aliases and
  678. never fetches the old gallery page; an ambiguous id returns `AMBIGUOUS_ALIAS`
  679. with candidate regions.
  680. `capture_atlas` accepts a known site slug only (plus an optional path on its
  681. known live origin), one viewport per call, components on by default and at most
  682. three hover/focus requests on the current active head. Click, type, submit,
  683. drag, keyboard navigation and route transitions are never performed.
  684. `refresh:false` reuses a matching usable head up to seven days old. A capture
  685. may return **partial evidence without publication**; `published` always states
  686. the actual result, `cached:true` means no new capture ran, and a failed or
  687. partial attempt leaves the previous head in place. Capture is still subject to
  688. robots and destination policy and one capture per cache at a time.
  689. `export_evidence_pack` builds a validated pack for 1–12 selected regions of one
  690. cached site. `includeMedia:"references"` (default) copies only derived
  691. summaries and references component packs and screenshots by artifact id, path
  692. and hash. `includeMedia:"permitted"` copies only stored artifacts with a caller
  693. rights assertion (`owned`, `licensed` or `permission`, `export_copy` scope, a
  694. non-empty reference); unknown or restricted artifacts are excluded with a
  695. reason. Assertions are recorded, not verified legal conclusions, and no
  696. assertion overrides a robots or destination refusal. There is no arbitrary
  697. output path, overwrite switch, asset downloader, public-sharing or publish
  698. operation; an identical selection returns the existing pack with `cached:true`.
  699. The Atlas CLI uses the existing `awwwards-index` executable:
  700. `--atlas import`, `--atlas capture --slug <slug> [--path /] --viewport
  701. desktop|mobile|both`, `--atlas reindex`, `--atlas verify` and
  702. `--atlas prune --older-than-days <N>` (dry-run unless `--apply`). Every action
  703. requires the flag, is mutually exclusive with the normal crawl, and validates
  704. its arguments before constructing a cache or client. There is no automatic
  705. capture after import and no new binary.
  706. Atlas is experimental: the classification gates are open, the tool release
  707. qualification is still pending, and captured page content remains its
  708. creators' property — this repository's MIT license does not cover it. See
  709. [ATLAS.md](./ATLAS.md) for the tool table, branch shapes, CLI rules, error
  710. codes, limits, unsupported operations and worked examples.
  711. ## Limitations
  712. Honest limits, so a result is not read as more than it measured.
  713. **The element corpus is partial after the gallery-crawl retirement.** The
  714. `/elements/*` gallery is not crawled. New records backfilled from winners' own
  715. site pages are created with `source: "site"`, `category: "uncategorized"` and
  716. an empty `builtWith` list, because those pages carry no facet taxonomy. The
  717. free-text `query` (title, author and slug tokens) is the reliable path. The
  718. `uncategorized` category matches site-derived rows; other facet categories and
  719. stack filters do not. An empty result does not prove the element does not exist.
  720. **`verify_build` scores structure and motion, not visual fidelity.** The band
  721. comparison returns one aggregate `bands.score` with `matched`/`refOnly`/
  722. `buildOnly` labels; it does not score individual bands. Band
  723. labels come from the structure scan as `#id.firstClass` (empty for anonymous
  724. wrappers). A unique, non-generic label is matched exactly; anonymous or
  725. duplicate labels fall back to same-tag plus closest height (within a 25% gap),
  726. so two different sections of similar height can pair. The structure walk is
  727. bounded: `maxBands` (default 40, smallest bands merged) caps the collapse step,
  728. and landmark splitting can then add sub-bands up to its own limit of 60, so a
  729. long or deeply nested page can still lose bands. `domDiff` reports
  730. `(incomplete)` when its scans were truncated, and `compact` drops the evidence
  731. lines. Capture timing can move the score: `waitStrategy: "load"` adds a 3 s
  732. settle, a full-screen preloader can be waited on for up to 15 s, and content
  733. that arrives after the capture (late fonts, images, hydration, animation) can
  734. change the bands or motion fingerprint between two runs of the same URL.
  735. Re-run before treating a delta as a regression; the score is evidence for a
  736. diff, not a grade.
  737. **`v2` is opt-in, not the default and not a 2.0 release.**
  738. `AWWWARDS_MCP_PROFILE=v2` replaces the default 41-tool surface (45 with
  739. `AWWWARDS_MCP_ATLAS=1`) with the 15-tool consolidated surface (16 with
  740. `AWWWARDS_MCP_ATLAS=1`) described in
  741. [awwwards-skills repository](https://github.com/INSANE0777/awwwards-skills). The default stays `full`; there
  742. are no aliases between the surfaces, and switching requires a server restart.
  743. **Third-party MCP directories are refreshed by their operators.** A listing
  744. such as Glama re-inspects this server on its own schedule; re-inspection there
  745. is a manual post-release admin step, not an API call or a code change in this
  746. repository.
  747. ## How it works
  748. - Live, polite scraping of awwwards.com public pages (max 1 request/second,
  749. robots.txt-compliant paths only, cached 7 days in SQLite at `~/.awwwards-mcp/`).
  750. - Screenshots are served from Awwwards' own CDN (880×660), cached on disk.
  751. - No API key, no account, no cost.
  752. ## Official Awwwards resources
  753. Awwwards publishes agent-facing, read-only resources:
  754. - [llms.txt](https://www.awwwards.com/llms.txt) — guidance for agents.
  755. - [openapi.json](https://www.awwwards.com/openapi.json) — OpenAPI 3.1 spec.
  756. - Annual Awards API — `https://www.awwwards.com/api/annual/categories`,
  757. `https://www.awwwards.com/api/annual/nominees/sites/{id}`,
  758. `https://www.awwwards.com/api/annual/nominees/users/{id}`.
  759. The three `get_annual_*` tools use this official public API (JSON:API) at
  760. 1 request/second with a 7-day local cache. Daily listings (SOTD, developer,
  761. honorable mentions, tags, colors) still use polite scraping of public
  762. pages. Media URLs returned by the annual tools are reference-only: full nominee
  763. payloads carry `mediaNote: "reference-only"`, and nothing is downloaded,
  764. mirrored, or redistributed.
  765. awwwards-mcp is an independent open-source project, not affiliated with or
  766. endorsed by Awwwards. Annual data is intended for personal, non-commercial
  767. design-inspiration use; Awwwards' terms and the featured creators' rights still
  768. apply.
  769. ## Ethics & terms
  770. This tool fetches publicly available pages for **personal design-inspiration
  771. use**, at human-ish request rates, honoring robots.txt. Awwwards' screenshots
  772. and content remain the property of Awwwards and the credited creators — don't
  773. bulk-scrape, redistribute, or republish them. If you use this commercially,
  774. review awwwards.com's terms yourself.
  775. ## Built with awwwards-mcp: seven real sites
  776. Four complete sites were built through the full inspiration loop this MCP
  777. enables, using nothing but the server's tools plus the shipped
  778. `awwwards-inspiration` skill. Each one exercised a different corner of the
  779. loop — and every correction the loop caught on the way became doctrine in the
  780. skill.
  781. > **Built in one shot, by a model that can't watch video.** All three sites
  782. > were built in a single prompt run on **GLM 5.3-flash** — which does not
  783. > support video input. The loop's motion study worked entirely from
  784. > frame-tiled filmstrips (ffmpeg, 1–2 fps per element) instead of watching
  785. > the recordings. With a video-native model, those same `get_site_elements`
  786. > videos and `record_site_motion` .webm files could be watched directly —
  787. > timing, easing and overlap read at full fidelity — and the motion-true
  788. > results would be better still. The skill's frame-tile doctrine is what
  789. > closes that gap today.
  790. **Watch the whole loop run (1:50):**
  791. <video src="assets/demo-loop.mp4" controls muted playsinline></video>
  792. *Screen recording of the agent running the `awwwards-inspiration` loop end to
  793. end with the awwwards MCP tools — searching SOTD references with inline
  794. screenshots, pulling design DNA, frame-studying element videos, building, and
  795. verifying with band maps + motion recording. If your client doesn't render
  796. the player, [watch the file directly](assets/demo-loop.mp4).*
  797. **1. [Ridge](showcase/ridge/index.html)**
  798. ([source](showcase/ridge/)) — a Swiss-minimal single-page showcase for a fictional engineering-talent studio, direction **Aspen Search** (SOTD + Developer Award, jury 7.48): monochrome `#FAFAF8`/`#1A1A1A` + mint, giant grotesque section markers, halftone grain, asymmetric panel grid, dark discipline panels in an interior **horizontal pin passage**, count-up stats, client rows, theme toggle, cursor-follower. Built with the v1.4.0 toolkit: FTS5-ranked direction search, **both-viewports** reference captures and QA (desktop 7,849px + mobile 390×844), overflow audit (0px both), pin-center shots, film verification — and the findings fed back into the skills. QA evidence: `showcase/ridge/_qa/`.
  799. **The grain-panel hover**, studied from aspensearch.com's recording and rebuilt as a canvas dither-dissolve — dots flip to mint around the mouse, the trail elongates, the boundary dissolves:
  800. ![Ridge grain-panel hover — canvas dither-dissolve following the mouse](assets/ridge-dither.gif)
  801. | Panel grid (desktop) | Horizontal discipline passage | Mobile 390×844 |
  802. |---|---|---|
  803. | ![Ridge desktop — Swiss panel grid with mint and grain](assets/ridge-home.jpg) | ![Ridge disciplines — pinned horizontal passage mid-slide](assets/ridge-disciplines.jpg) | ![Ridge mobile — stacked grid, zero overflow](assets/ridge-mobile.jpg) |
  804. **2. [Fallow Press](showcase/fallow-press/index.html)**
  805. ([source](showcase/fallow-press/)) — a flat-2D editorial journal, direction
  806. **Emergence Magazine** (SOTD): pink `#FF9398` on cream and black, torn-paper
  807. masthead (pure CSS `clip-path`, zero WebGL), giant grotesque display over
  808. grayscale photography, serif-italic brand, three pages with **separate
  809. horizontal** projects/about pages (GSAP ScrollTrigger pin +
  810. `containerAnimation`).
  811. | Torn-paper masthead (home) | Horizontal gallery (Fields) | Horizontal chapters (Practices) |
  812. |---|---|---|
  813. | ![Fallow Press home — torn-paper masthead over grayscale photography](assets/fallow-home.jpg) | ![Fallow Press Fields — pinned horizontal gallery panel](assets/fallow-fields.jpg) | ![Fallow Press Practices — pink quote chapter](assets/fallow-practices.jpg) |
  814. The loop as it ran:
  815. 1. `search_sites` (magazine filters) → shortlist judged from inline
  816. screenshots → `get_site_details` on Emergence Magazine.
  817. 2. **Capture before building**: `capture_live_site` + `record_site_motion`
  818. on the live site *first*; full-page PNG and motion .webm kept in
  819. [showcase/fallow-press/ref-motion/](showcase/fallow-press/ref-motion/) as the evidence trail.
  820. 3. Build, then verify: full-page capture plus **panel-center pin shots** of
  821. both horizontal pages (13 stops each, in
  822. [showcase/fallow-press/_qa/](showcase/fallow-press/_qa/) — `capture-qa.mjs` is reusable).
  823. 4. The pin shots caught a real bug: horizontal-panel entrances used
  824. `toggleActions: "play none none reverse"`, and 100vw panels hide content
  825. at midpoints on the way back — copy disappeared mid-view. Fix
  826. (one-shot play entrances) is now doctrine: **full-viewport panels get
  827. one-shot entrances**; QA pin shots land at panel **centers**, not uniform
  828. fractions, or you photograph empty transition zones.
  829. **3. Cerebrium recreation** (`C:/Users/Afjal/cerebrium-recreation/`) — a
  830. fidelity-first recreation of cerebrium.ai, pixel-checked against the live
  831. reference: full-page captures of both sides, `analyze_page_structure` band
  832. compare, and SVG icon/legend fixes until the build matched the reference to
  833. within 1px of total page height (10,871px vs 10,870px). This is the
  834. **structure-before-pixels** doctrine at its strictest — band maps compared,
  835. never just totals.
  836. ![Cerebrium recreation — full-page build capture](assets/cerebrium-build.jpg)
  837. **4. The Meridian** (`C:/Users/Afjal/editorial-site/`) — an editorial journal
  838. built from ORDR/Hearst references: the first build to run the whole loop
  839. end-to-end. `analyze_page_structure` caught a masthead band bug by comparing
  840. the build's band map against the reference's; the reference captures,
  841. motion film, and the reusable pre-scroll capture script live in
  842. `editorial-site/_qa/`.
  843. ![The Meridian editorial journal — full-page build capture](assets/meridian-build.jpg)
  844. ![The Meridian — motion filmstrip from record_site_motion](assets/meridian-filmstrip.jpg)
  845. **5. NEUTOMNI one-shot rehost** (`A:/nio/`) — a 1:1 capture-and-rehost of
  846. neutomni.com built in a single MCP pass: the live page was captured with the
  847. toolset and re-served locally with the site's own DOM, stylesheet, and scripts
  848. (relaunched as a standalone static copy — no CMS, no build step). This is the
  849. **migration-recovery** posture: for sites you own or are authorized to
  850. rehost when the original vendor vanishes. Faithful because nothing was
  851. re-derived — geometry, motion, and copy come along exactly.
  852. The full build lives in the repo: [`showcase/neutomni/`](showcase/neutomni/) —
  853. open `index.html` directly, no server or build step needed.
  854. ![NEUTOMNI rehost — loader band with the giant wordmark](assets/neutomni-rehost-loader.png)
  855. ![NEUTOMNI rehost — nav, hero, and the pharmacy-type band](assets/neutomni-rehost-hero.png)
  856. ![NEUTOMNI rehost — the statement section](assets/neutomni-rehost-statement.png)
  857. ![NEUTOMNI rehost — the four red process panels](assets/neutomni-rehost-process.png)
  858. ![NEUTOMNI rehost — Selected Work with the RSB tablet mockup](assets/neutomni-rehost-work.png)
  859. ![NEUTOMNI rehost — focus statement on the blue gradient](assets/neutomni-rehost-focus.png)
  860. ![NEUTOMNI rehost — pricing cards, Essentials to Enterprise](assets/neutomni-rehost-pricing.png)
  861. ![NEUTOMNI rehost — desktop with the Pricing.html window](assets/neutomni-rehost-desktop-pricing.png)
  862. ![NEUTOMNI rehost — Win-95 desktop with the pricing TV](assets/neutomni-rehost-desktop.png)
  863. ![NEUTOMNI rehost — red footer with contact and wordmark](assets/neutomni-rehost-footer.png)
  864. **6. NEUTOMNI study recreation** ([`showcase/nio/`](showcase/nio/index.html)) — a hand-built recreation of neutomni.com reconstructed from MCP evidence (band map, component packs, scroll/hover censuses, motion DNA, pose capture) rather than rehosted markup: authored HTML/CSS/JS with GSAP + ScrollTrigger + Lenis, sourced fonts/images/audio vendored locally. Ships with the mandatory study-build disclaimer and a full provenance list in its own README — a private reference build, **not for publication**; replace the borrowed assets before any real use. This is the `recreate` skill's end-to-end artifact.
  865. **7. Two26 Studio study recreation** ([`showcase/two26/`](showcase/two26/index.html)) — a hand-authored recreation of two26.studio built with the 1.14 MCP. The site is an inner-scroller page (`body{position:fixed}` + `.page{overflow-y:auto}`): `analyze_page_structure` now reports `scrollRoot: div.page` and the full 13,103px band map; `capture_live_site` waits out the preloader, then returns `mode:"anchors"` — six ordered viewport shots down that inner scroller (JSON paths, no inline image). Built from eight component packs, scroll/hover censuses + motion DNA, with 13 GSAP triggers (2 scrubs, 1 pin), local fonts/media, QA at five viewports, and a 54-file provenance list in its README. Mandatory study-build disclaimer: **not for publication**; replace borrowed assets before any real use.
  866. ![Two26 Studio study recreation — hero](assets/two26-hero.png)
  867. ## Skills used to build these
  868. | Skill | Role in the builds |
  869. |---|---|
  870. | `awwwards-inspiration` | The 8-step loop itself (from the [awwwards-skills repository](https://github.com/INSANE0777/awwwards-skills)): search → judge from screenshots → design DNA → capture/motion study → state direction → build → band-map verify. |
  871. | `awwwards-design-md` | Builds a cited DESIGN.md plus evidence sidecar for one public URL from tokens, structure, screenshot and up to three components. |
  872. | `gsap-scrolltrigger` | The horizontal pin + `containerAnimation` pattern (ease `"none"`, one-shot entrances) driving both Fallow Press horizontal pages. |
  873. | `gsap-core` / `gsap-timeline` | Tween composition and sequenced hero entrances (torn-paper drop, panel copy rises). |
  874. | `frontend-design` | Typography, palette and layout judgment applied when translating reference DNA into original pages. |
  875. | `lenis` (library, via skill guidance) | smooth scrolling synced to ScrollTrigger on the Fallow Press home page. |
  876. | `tailwindcss` / plain CSS | All builds are plain hand-rolled CSS — flat 2D, no frameworks needed. |
  877. **The skills live in the [awwwards-skills repository](https://github.com/INSANE0777/awwwards-skills):** that repository is their source of truth, including the `_memory/techniques.json` registry of researched how-tos per domain (video understanding, motion detection, UI structure, micro-interactions, images). Skill changes land there; this MCP repository does not carry skill copies.
  878. Reduced-motion, JS-less visits, and capture tools all get graceful fallbacks
  879. (vertical stacks; progressive-enhancement reveals).
  880. **What the verification loop caught** — proof the structure-before-pixels
  881. doctrine is load-bearing:
  882. - Element **posters lie**: the first showcase build was designed from poster
  883. frames alone and rendered a spinning 3D ring as *floating static cards*.
  884. Downloading the element videos (`get_site_elements`) and frame-tiling them
  885. revealed the motion truth — now the skill mandates studying motion before
  886. animating.
  887. - Full-page captures of reveal-on-scroll builds showed blank sections: `.reveal`
  888. animation state vs capture's no-scroll reality. Builds ship
  889. content-visible-without-JS progressive enhancement.
  890. - Horizontal-panel copy vanished **mid-view** on the Fallow Press pages:
  891. `toggleActions` reverse reverts entrances while a 100vw panel is still
  892. holding the viewport (see above).
  893. - Band-map compare kept the references' rhythm instead of drifting on
  894. section heights (Cerebrium, The Meridian).
  895. Prompt counts: **3** for the original showcase build (the build ask, the
  896. motion correction that exposed the poster-lie, the structure pass) and
  897. **1** for Fallow Press ("create a new website using our MCP and skills… no
  898. 3D websites") — its two follow-ups were caught by the QA loop, not by the
  899. user. Each correction became doctrine in the shipped `awwwards-inspiration`
  900. skill: frame-study element videos before animating; judge page architecture
  901. from the studied passages; tile per element, not one giant filmstrip;
  902. capture live sites and animation **before** building.
  903. ## Can awwwards-mcp crawl the sitemap? (robots.txt notes)
  904. The awwwards.com `robots.txt` advertises
  905. `Sitemap: https://www.awwwards.com/sitemap.xml` and — verified live
  906. 2026-09-18 — **that sitemap URL returns a soft-404 HTML page** (as do common
  907. child names like `/sitemap-websites.xml`). So sitemap discovery isn't
  908. currently a path to more data; the polite crawl surface is exactly what the
  909. indexer uses:
  910. - **Allowed and used**: `/websites/`, `/websites/<filter>/`, `/sites/<slug>`
  911. (one filter per URL; deep pagination stays un-crawled).
  912. - **Disallowed**: `/tag/`, `/search-websites`,
  913. `/websites/?` (query-string pagination), `/elements/*` (not fetched since
  914. v1.16.0; the gallery crawl was removed; the client rejects these paths),
  915. `/vote/`, favourites/likes/follows, and the rest of the 33 rules.
  916. - Our client (`src/awwwards.ts` `buildFilterUrl`) constructs **only**
  917. `/websites/…` paths at 1 request/second — the loop stays inside the
  918. published rules by construction, not by convention.
  919. ## Star History
  920. <a href="https://www.star-history.com/?repos=insane0777%2Fawwwards-mcp&type=date&legend=top-left">
  921. <picture>
  922. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=insane0777/awwwards-mcp&type=date&theme=dark&legend=top-left" />
  923. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=insane0777/awwwards-mcp&type=date&legend=top-left" />
  924. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=insane0777/awwwards-mcp&type=date&legend=top-left" />
  925. </picture>
  926. </a>
  927. ## Sponsor
  928. awwwards-mcp is free and MIT-licensed. If it saves you time, you can
  929. [sponsor development on GitHub](https://github.com/sponsors/INSANE0777).
  930. Sponsorship is optional and does not change the licence or the tool contracts.
  931. ## Contributing
  932. PRs welcome! The project especially needs **parser-drift fixes** — when live
  933. awwwards.com markup changes, a fresh HTML snapshot attached to an issue often
  934. becomes the new test fixture and the fastest merged PR. See
  935. [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide:
  936. **Parser-drift is monitored automatically.** A probe script
  937. ([scripts/parser-drift-probe.mjs](scripts/parser-drift-probe.mjs),
  938. `npm run drift`) checks every markup anchor the parsers depend on — the
  939. `split`/`indexOf`/regex literals in `src/parsers.ts` — against the live
  940. listing and detail pages (2 fetches, 1 request/second, same politeness as
  941. the client). A daily GitHub Action ([.github/workflows/parser-drift.yml](.github/workflows/parser-drift.yml))
  942. runs it and, on drift, opens/updates a single tracking issue with the exact
  943. anchors that changed (and auto-closes it when a later run is green). To run
  944. it yourself: `npm run drift` (live, exit code 0/1/2) or `npm run drift -- --fixture`
  945. (offline, checks the committed fixtures still feed every anchor). Raw HTML
  946. is never diffed or stored — anchors only fire when the parsers actually
  947. break, so there are no false alarms from cosmetic tweaks.
  948. - Development setup & project layout (offline fixture-tested, no network in tests)
  949. - How to create a PR: fork → `fix/`/`feat/`/`docs/` branch → typecheck + tests → PR template
  950. - The politeness constraints new code must keep (1 req/s, robots.txt paths, light runtime deps)
  951. Bugs and feature ideas start as
  952. [issues](https://github.com/INSANE0777/Awwwards-mcp/issues/new/choose) with
  953. templates. Security problems go privately — see
  954. [SECURITY.md](SECURITY.md). By participating you agree to the
  955. [Code of Conduct](CODE_OF_CONDUCT.md).
  956. ## Development
  957. ```bash
  958. npm install
  959. npm test # offline unit tests against committed HTML fixtures
  960. npm run smoke # manual live smoke test against awwwards.com
  961. npm run build # compile to dist/
  962. ```
  963. MIT — see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.