# Awwwards MCP

> Independent, open-source Model Context Protocol server that gives AI agents design evidence from award-winning websites: ranked references, design DNA, page captures, section maps, scroll and hover censuses, motion fingerprints, design tokens and build verification.

Canonical: https://awwwards-mcp.vercel.app/
Repository: https://github.com/INSANE0777/Awwwards-mcp
npm: https://www.npmjs.com/package/awwwards-mcp
Skills: https://github.com/INSANE0777/awwwards-skills
Version: 1.19.0

## What it does

Awwwards MCP runs locally over stdio. It needs no API key and calls no model. It turns a design direction into evidence an agent can build from:

- Search the Awwwards archive by query, colour, tag, technology or award.
- Read a site's recorded design DNA, palette, type, elements and stack.
- Capture full-page or anchored screenshots, section geometry and computed CSS.
- Census scroll triggers, hover states and runtime motion.
- Export design tokens, image audits and component packs.
- Convert a single-file rebuild to Vite, Astro or Next.js.
- Verify a build against the reference it came from.

## Tools

- `search_sites`: search the Awwwards archive.
- `get_site_details`: read a site's recorded design DNA.
- `create_design_brief`: synthesise a direction from several references.
- `capture_live_site`: capture a live page as a saved screenshot plus inline preview (full mode), or six ordered section anchors for inner scrollers. It does not return page HTML.
- `analyze_page_structure`: read bands, section order, geometry and computed styles.
- `analyze_scroll_map`: census scroll triggers and scrubbed timelines.
- `search_atlas`, `get_atlas`, `capture_atlas`, `export_evidence_pack`: experimental, opt-in Atlas evidence (set `AWWWARDS_MCP_ATLAS=1`). Labels and inferred component types are candidate-only; F9 held-out precision is unmet; evidence packs stay local. In v2 only `export_evidence_pack` is added and the other Atlas capabilities are branches.
- `get_motion_dna`: fingerprint the site's runtime motion.
- `capture_component`: capture a section or component with styles and assets.
- `build_project`: convert a single-file rebuild into a project.
- `verify_build`: compare a build against its reference.

## Install

```bash
npm install -g awwwards-mcp
```

Browser capture and motion evidence:

```bash
npm install -g awwwards-mcp playwright ffmpeg-static
playwright install chromium
```

## Profiles

- `AWWWARDS_MCP_PROFILE=full` exposes 41 tools (45 with Atlas).
- `AWWWARDS_MCP_PROFILE=core` exposes 13 tools.
- `AWWWARDS_MCP_PROFILE=v2` exposes 15 tools (16 with Atlas) and is beta.
- `AWWWARDS_CACHE_DIR` moves the local cache. Atlas CLI: `awwwards-index --atlas import|capture|reindex|verify|prune`.

## Connect an agent

The server is plain stdio with command `awwwards-mcp`.

- Claude Code: `claude mcp add --scope user awwwards -- awwwards-mcp`
- Codex: `codex mcp add awwwards -- awwwards-mcp`, or `[mcp_servers.awwwards] command = "awwwards-mcp" args = []` in `~/.codex/config.toml`
- OpenCode 2: `opencode mcp add awwwards -- awwwards-mcp`, or nest `"awwwards": { "type": "local", "command": ["awwwards-mcp"] }` under `mcp.servers` in `opencode.json`
- Cursor: `.cursor/mcp.json` with `"mcpServers": { "awwwards": { "type": "stdio", "command": "awwwards-mcp" } }`
- VS Code: `.vscode/mcp.json` with `"servers": { "awwwards": { "type": "stdio", "command": "awwwards-mcp" } }`
- Claude Desktop, Windsurf, Cline, Gemini CLI: common `mcpServers` JSON with `"command": "awwwards-mcp"`

Restart the client after adding the server. Playwright is needed for browser captures and structure; ffmpeg-static is only needed for motion recording. Run `playwright install chromium` after installing Playwright.

## Agent skills

Install with:

```bash
npx skills add INSANE0777/awwwards-skills
```

Available skills (nine): `awwwards-atlas`, `awwwards-setup`, `awwwards-inspiration`, `recreate`, `awwwards-motion-study`, `awwwards-section-loop`, `motion-authoring`, `awwwards-doctor`, `awwwards-design-md`.

## Independence

Awwwards MCP is not affiliated with or endorsed by Awwwards. The Awwwards name, screenshots and site media belong to Awwwards and the credited creators. Use the server for personal, non-commercial design research and review the original terms before publishing anything derived from it.