awwwards-mcp

Free, open-source MCP server that gives AI agents design inspiration from Awwwards — the Mobbin-style visual reference loop, sourced from the web's best award-winning websites.

Your agent searches in natural language ("dark 3D portfolio sites", "soft pastel e-commerce"), sees real screenshots inline, and can pull the design DNA of any site: color palette, tech stack, design elements, award history. Free-text queries run on a porter-stemmed, prefix-matching FTS5 index with BM25 ranking — "magazines" now finds Magazine-tagged sites (68 on the live index), best matches first, where the old substring path returned zero. Multi-word queries keep AND semantics: every token must hit the same site.

Tools

Setup

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.

Skills

This package ships three agent skills. Any agent that follows the Agent Skills standard can load them; copy them into your agent's skills directory:

npm install awwwards-mcp
mkdir -p ~/.agents/skills && cp -r node_modules/awwwards-mcp/skills/awwwards-inspiration node_modules/awwwards-mcp/skills/awwwards-doctor node_modules/awwwards-mcp/skills/awwwards-motion-study ~/.agents/skills/

Windows: run this from Git Bash, or copy node_modules\awwwards-mcp\skills\awwwards-inspiration manually.

Indexing (recommended)

search_sites works out of the box, but its depth is limited by polite live scraping (~31 sites per filter page). Build a local index once and searches draw from thousands of award-winning sites instantly:

npx -y -p awwwards-mcp awwwards-index      # once published
# or, from a local checkout of this repo:
npm run index

• Crawls all ~200 tag pages at 1 request/second (~4 minutes) into the local SQLite cache at ~/.awwwards-mcp/.
• Resumable: interrupt it and re-run — completed pages are skipped.
• The MCP server re-indexes automatically in the background whenever the index is older than 7 days (never blocking your session).

Site details (palettes, tech stacks) are still fetched on demand and cached for 7 days.

How it works

• Live, polite scraping of awwwards.com public pages (max 1 request/second, robots.txt-compliant paths only, cached 7 days in SQLite at ~/.awwwards-mcp/).
• Screenshots are served from Awwwards' own CDN (880×660), cached on disk.
• No API key, no account, no cost.

Ethics & terms

This tool fetches publicly available pages for personal design-inspiration use, at human-ish request rates, honoring robots.txt. Awwwards' screenshots and content remain the property of Awwwards and the credited creators — don't bulk-scrape, redistribute, or republish them. If you use this commercially, review awwwards.com's terms yourself.

Built with awwwards-mcp: four real sites

Four complete sites were built through the full inspiration loop this MCP enables, using nothing but the server's tools plus the shipped awwwards-inspiration skill. Each one exercised a different corner of the loop — and every correction the loop caught on the way became doctrine in the skill.

Built in one shot, by a model that can't watch video. All three sites were built in a single prompt run on GLM 5.3-flash — which does not support video input. The loop's motion study worked entirely from frame-tiled filmstrips (ffmpeg, 1–2 fps per element) instead of watching the recordings. With a video-native model, those same get_site_elements videos and record_site_motion .webm files could be watched directly — timing, easing and overlap read at full fidelity — and the motion-true results would be better still. The skill's frame-tile doctrine is what closes that gap today.

1. Ridge (source) — 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 skill-memory flywheel recorded the findings. QA evidence: showcase/ridge/_qa/.

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:

2. Fallow Press (source) — a flat-2D editorial journal, direction Emergence Magazine (SOTD): pink #FF9398 on cream and black, torn-paper masthead (pure CSS clip-path, zero WebGL), giant grotesque display over grayscale photography, serif-italic brand, three pages with separate horizontal projects/about pages (GSAP ScrollTrigger pin + containerAnimation).

The loop as it ran:

1. search_sites (magazine filters) → shortlist judged from inline screenshots → get_site_details on Emergence Magazine.
2. Capture before building: capture_live_site + record_site_motion on the live site first; full-page PNG and motion .webm kept in fallow-press/ref-motion/ as the evidence trail.
3. Build, then verify: full-page capture plus panel-center pin shots of both horizontal pages (13 stops each, in fallow-press/_qa/ — capture-qa.mjs is reusable).
4. The pin shots caught a real bug: horizontal-panel entrances used toggleActions: "play none none reverse", and 100vw panels hide content at midpoints on the way back — copy disappeared mid-view. Fix (one-shot play entrances) is now doctrine: full-viewport panels get one-shot entrances; QA pin shots land at panel centers, not uniform fractions, or you photograph empty transition zones.

3. Cerebrium recreation (C:/Users/Afjal/cerebrium-recreation/) — a fidelity-first recreation of cerebrium.ai, pixel-checked against the live reference: full-page captures of both sides, analyze_page_structure band compare, and SVG icon/legend fixes until the build matched the reference to within 1px of total page height (10,871px vs 10,870px). This is the structure-before-pixels doctrine at its strictest — band maps compared, never just totals.

4. The Meridian (C:/Users/Afjal/editorial-site/) — an editorial journal built from ORDR/Hearst references: the first build to run the whole loop end-to-end. analyze_page_structure caught a masthead band bug by comparing the build's band map against the reference's; the reference captures, motion film, and the reusable pre-scroll capture script live in editorial-site/_qa/.

Skills used to build these

The skills self-improve: every loop pass records what verification caught (scripts/skill-memory.mjs record), and a deterministic distiller folds rules seen 2+ times into your installed skill copy — while the shipped copies only change via human PR. A techniques registry (skills/_memory/techniques.json) catalogs researched how-tos per domain (video understanding, motion detection, UI structure, micro-interactions, images).

Reduced-motion, JS-less visits, and capture tools all get graceful fallbacks (vertical stacks; progressive-enhancement reveals).

What the verification loop caught — proof the structure-before-pixels doctrine is load-bearing:

• Element posters lie: the first showcase build was designed from poster frames alone and rendered a spinning 3D ring as floating static cards. Downloading the element videos (get_site_elements) and frame-tiling them revealed the motion truth — now the skill mandates studying motion before animating.
• Full-page captures of reveal-on-scroll builds showed blank sections: .reveal animation state vs capture's no-scroll reality. Builds ship content-visible-without-JS progressive enhancement.
• Horizontal-panel copy vanished mid-view on the Fallow Press pages: toggleActions reverse reverts entrances while a 100vw panel is still holding the viewport (see above).
• Band-map compare kept the references' rhythm instead of drifting on section heights (Cerebrium, The Meridian).

Prompt counts: 3 for the original showcase build (the build ask, the motion correction that exposed the poster-lie, the structure pass) and 1 for Fallow Press ("create a new website using our MCP and skills… no 3D websites") — its two follow-ups were caught by the QA loop, not by the user. Each correction became doctrine in the shipped awwwards-inspiration skill: frame-study element videos before animating; judge page architecture from the studied passages; tile per element, not one giant filmstrip; capture live sites and animation before building.

Can awwwards-mcp crawl the sitemap? (robots.txt notes)

The awwwards.com robots.txt advertises Sitemap: https://www.awwwards.com/sitemap.xml and — verified live 2026-09-18 — that sitemap URL returns a soft-404 HTML page (as do common child names like /sitemap-websites.xml). So sitemap discovery isn't currently a path to more data; the polite crawl surface is exactly what the indexer uses:

• Allowed and used: /websites/, /websites/<filter>/, /sites/<slug> (one filter per URL; deep pagination stays un-crawled).
• Disallowed and never fetched: /tag/, /search-websites, /websites/? (query-string pagination), /elements/*, /vote/, favourites/likes/follows, and the rest of the 33 rules.
• Our client (src/awwwards.ts buildFilterUrl) constructs only /websites/… paths at 1 request/second — the loop stays inside the published rules by construction, not by convention.

Contributing

PRs welcome! The project especially needs parser-drift fixes — when live awwwards.com markup changes, a fresh HTML snapshot attached to an issue often becomes the new test fixture and the fastest merged PR. See CONTRIBUTING.md for the full guide:

Parser-drift is monitored automatically. A probe script (scripts/parser-drift-probe.mjs, npm run drift) checks every markup anchor the parsers depend on — the split/indexOf/regex literals in src/parsers.ts — against the live listing and detail pages (2 fetches, 1 request/second, same politeness as the client). A daily GitHub Action (.github/workflows/parser-drift.yml) runs it and, on drift, opens/updates a single tracking issue with the exact anchors that changed (and auto-closes it when a later run is green). To run it yourself: npm run drift (live, exit code 0/1/2) or npm run drift -- --fixture (offline, checks the committed fixtures still feed every anchor). Raw HTML is never diffed or stored — anchors only fire when the parsers actually break, so there are no false alarms from cosmetic tweaks.

• Development setup & project layout (offline fixture-tested, no network in tests)
• How to create a PR: fork → fix//feat//docs/ branch → typecheck + tests → PR template
• The politeness constraints new code must keep (1 req/s, robots.txt paths, light runtime deps)

Bugs and feature ideas start as issues with templates. Security problems go privately — see SECURITY.md. By participating you agree to the Code of Conduct.

Development

npm install
npm test        # offline unit tests against committed HTML fixtures
npm run smoke   # manual live smoke test against awwwards.com
npm run build   # compile to dist/

MIT — see LICENSE.