webcontext-mcp

Give your AI designer eyes.

An MCP server that extracts the visual DNA from any website - colors, typography, spacing, layout, motion so Cursor, Claude Code, and more build UI that looks designed, not generated.

The Problem

AI coding agents are blind.

Ask Cursor to "build a dark SaaS landing page" and you get:

• Centered text (safe default)
• Fake terminal UIs with $ prompts
• Lime green or purple accents (training data bias)
• Shadow cards and rounded-full pills

The AI isn't lazy. It has never seen a website. It reads HTML, not design.

The Solution

webcontext-mcp captures screenshots + extracts real CSS + analyzes visual language with a vision model. It returns structured design context that your agent consumes automatically through the Model Context Protocol.

Before: Generic template
After: Precise, intentional design

Same AI. Different context.

Demo

"Use https://linear.app as a design reference for my landing page."

Without context → AI guesses. Centered hero. Fake dashboard. Neon accents.
With webcontext → AI sees. Left-aligned. Flat surfaces. Exact hex codes. No fake UI.

Installation

1. Add to Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "webcontext": {
      "command": "npx",
      "args": ["-y", "webcontext-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-openrouter-api-key-here",
        "OPENROUTER_MODEL": "google/gemini-2.5-flash"
      }
    }
  }
}

OPENROUTER_MODEL is optional — omit it to use the default (google/gemini-2.5-flash).

Restart Cursor.

2. Install Chromium (first run only)

npx playwright install chromium

Configuration

Environment variables (set in mcp.json env or a .env file in the project root):

| Variable | Required | Default | Description | | -------------------- | -------- | ------------------------- | -------------------------------------------------------------------- | | OPENROUTER_API_KEY | Yes | — | Your OpenRouter API key | | OPENROUTER_MODEL | No | google/gemini-2.5-flash | Vision model ID for design analysis (e.g. google/gemini-2.5-flash) |

On startup the server logs which model is active, e.g. [webcontext] Using model: google/gemini-2.5-flash.

Usage

Mention any URL in chat. The agent calls analyze_website automatically.

Build a landing page for my dev tool. Use https://linear.app as reference.

Or call it explicitly:

Use the analyze_website tool on https://stripe.com

What you get back

1. Design DNA JSON - structured visual language:

   • Color system (exact hex codes)
   • Typography (font, scale, hierarchy)
   • Spacing (padding, max-width, density)
   • Surface treatment (flat vs. shadow, border style)
   • Layout patterns (hero composition, feature rhythm)
   • Motion (transitions, hover behavior)
   • Anti-patterns (what this design never does)

2. Desktop screenshot - JPEG base64 for visual reference

The AI applies this DNA to your product. It does not clone the reference site's content, brand, or fake UI.

How it works

URL → Playwright screenshot (desktop)
  ↓
CSS extraction (colors, fonts, animations)
  ↓
Vision model analysis (OpenRouter — default: Gemini 2.5 Flash Preview)
  ↓
Structured design DNA + screenshot → AI coding agent

BYOK - Bring Your Own Key. Runs locally. No hosted backend. No shared quota. You pay OpenRouter directly; typically fractions of a cent per analysis.

Why MCP?

The Model Context Protocol means zero friction:

• Cursor starts the server automatically when needed
• No auth, no dashboard, no copy-paste
• The AI decides when to call the tool based on your prompt
• Works with Claude Code, Cline, and any MCP-compatible client

Output example

{
  "url": "https://linear.app/",
  "designDNA": {
    "visualPhilosophy": "Dark minimalism with surgical precision. Every element earns its place, contributing to a sense of focused efficiency.",
    "mood": "focused, efficient, high-tech, precise, sophisticated",
    "colorSystem": {
      "background": {
        "hex": "#08090a",
        "usage": "Primary page background, dark and immersive."
      },
      "surface": {
        "hex": "#0f1011",
        "usage": "Main card backgrounds, slightly lighter than the base background."
      },
      "textPrimary": {
        "hex": "#d0d6e0",
        "usage": "Headings, important text, high contrast."
      },
      "textSecondary": {
        "hex": "#8a8f98",
        "usage": "Body text, captions, muted."
      }
    },
    "typography": {
      "family": "Inter Variable",
      "scale": "Massive hero (4xl-6xl) → Section headlines (2xl-3xl) → Body (lg) → Labels (sm-xs)"
    },
    "spacing": {
      "sectionPadding": "96px-128px vertical between major content blocks.",
      "contentMaxWidth": "1200px centered."
    },
    "motion": {
      "transitions": "Fast 0.1s-0.16s duration."
    },
    "antiPatterns": [
      "NEVER build fake product UI with HTML/CSS (tickets, terminals, dashboards, progress bars)",
      "NEVER use bright accent backgrounds for cards or testimonials",
      "NEVER use shadow-heavy cards or elevation"
    ]
  }
}

Requirements

• Node.js 18+
• OpenRouter API key
• Playwright Chromium (auto-installed on first run)

License

MIT