PicassoWeb MCP

"Good artists copy, great artists steal." — the tool formerly known as webcopy-design-mcp.

PicassoWeb opens a website in Chromium and turns its rendered interface into everything an AI client needs to replicate it faithfully. It extracts the actual computed colors, typography, CSS variables, layout primitives, and reusable component families instead of only searching the raw source for CSS strings. Beyond the design system, it can screenshot the page, download the real assets (images, inline SVG logos/icons, fonts, video), extract the motion design (@keyframes, transitions, animation libraries, scroll reveals), capture JS-driven motion over time as frame strips and numeric curves, map the layout tree, clone a section to self-contained HTML + CSS + assets, crawl same-origin pages into a site-wide design system, produce a complete one-shot replication kit, and pixel-diff a replica against the original so an agent can iterate until the copy matches.

Website: blackridder22.github.io/PicassoWeb

Documentation: Introduction · Quick start · Tool reference · Workflows · Security · llms.txt

What it extracts

• Color palette normalized to hex, with usage counts for text, backgrounds, borders, decoration, SVG fills, and strokes.

• Font families, weights, styles, type sizes, line heights, letter spacing, and representative selectors.

• CSS custom properties classified as color, typography, spacing, radius, shadow, or other tokens.

• Common border radii, box shadows, margins, padding, and gaps.

• Component families such as buttons, inputs, cards, navigation, headers, footers, modals, tabs, accordions, badges, avatars, forms, tables, heroes, and pagination.

• Detailed inspection by CSS selector, accessible role/name, or text — including open shadow roots and same-origin frames — with computed styles, matched cascade rules, custom properties, box-model geometry, platform fonts, pseudo-elements, descendants, and interaction states.

JavaScript-rendered pages are supported. By default, the analyzer also scrolls through the page to trigger lazy-rendered sections before extraction.

Related MCP server: mcp-mirage-brand-extract

MCP tools

All tools return the complete JSON result first for compatibility, plus typed MCP structured content with result and guidance (nextTools, warnings, cost, file behavior, and session policy). capture_screenshot, clone_section, create_replication_kit, compare_replica, capture_interactions, and capture_motion additionally return image content blocks.

Session reuse

Read-style tools (analyze_site, inspect_component, capture_screenshot, extract_assets, extract_animations, extract_layout, clone_section) share a small cache of loaded pages keyed by URL + viewport. Consecutive calls against the same page skip the full navigation — typically 2–5s saved per call — and note the reuse in warnings. Sessions expire after 2 minutes; tools that mutate page state (extract_responsive, create_replication_kit, compare_replica, capture_interactions, capture_motion, crawl_site) always load fresh.

Tools that write files

extract_assets, create_replication_kit, clone_section (with outputDir), extract_responsive (with outputDir), capture_interactions (with outputDir), capture_motion (with outputDir), crawl_site (with outputDir), and capture_screenshot (with outputPath) write to the local filesystem, so they are not marked read-only. Every downloaded asset URL is re-checked against the same SSRF guard as the initial navigation.

Quick start (npx)

Requirements: Node.js 20 or newer. Add PicassoWeb to your MCP client configuration — no clone, no build:

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

AI tool profiles

full remains the default and advertises all 14 tools. Use the focused workflow profile to advertise only the nine intent-level tools and reduce overlap for agents:

{
  "mcpServers": {
    "picassoweb": {
      "command": "npx",
      "args": ["-y", "picassoweb", "--tools", "workflow"]
    }
  }
}

PICASSOWEB_TOOLS=workflow is equivalent. Both profiles receive workflow routing through MCP server instructions, decision-first tool descriptions, typed output schemas, and machine-readable cost/session metadata.

The same canonical catalog generates the AI tool reference, llms.txt, and packaged PicassoWeb skill, so agent guidance stays version-matched with the server.

The first run downloads the package and a Chromium build (~130 MB, cached after that). If Chromium is already installed, point the server at it instead:

{
  "mcpServers": {
    "picassoweb": {
      "command": "npx",
      "args": ["-y", "picassoweb"],
      "env": { "CHROME_EXECUTABLE_PATH": "/absolute/path/to/chromium" }
    }
  }
}

Install from source

git clone https://github.com/blackridder22/PicassoWeb.git
cd PicassoWeb
npm install          # also downloads Chromium via postinstall
npm run build

Connect an MCP client (from source)

Build the project, then add a stdio server to your MCP client configuration. Replace the example path with the absolute project path.

{
  "mcpServers": {
    "picassoweb": {
      "command": "node",
      "args": ["/absolute/path/to/webcopy-design-mcp/dist/index.js"]
    }
  }
}

During development, the client can launch the TypeScript entry point directly:

{
  "mcpServers": {
    "picassoweb-dev": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/webcopy-design-mcp/src/index.ts"]
    }
  }
}

The MCP server communicates over standard input/output. Diagnostic messages are written only to standard error.

Example calls

Analyze a public site:

{
  "url": "https://example.com",
  "viewportWidth": 1440,
  "viewportHeight": 900,
  "maxElements": 2500,
  "autoScroll": true
}

Inspect a component after the overview identifies a useful selector:

{
  "url": "https://example.com",
  "selector": ".pricing-card",
  "maxMatches": 5
}

Targeting can instead use an accessible role/name or visible text, and can be scoped to an iframe. Exactly one of selector, role, or text is required. Component inspection now defaults autoScroll to false; if the target is not initially attached, PicassoWeb performs one lazy-content scroll and retries automatically.

{
  "url": "https://example.com",
  "role": "button",
  "roleName": "Sign in",
  "frameSelector": "iframe.checkout"
}

Analyze source supplied directly by an agent or another tool:

{
  "html": "<main><article class=\"card\"><h2>Hello</h2></article></main>",
  "css": ":root{--brand:#6d5dfc}.card{padding:24px;color:var(--brand)}"
}

Docker

The image uses the official Playwright runtime, so Chromium and its system libraries are already present.

docker build -t picassoweb-mcp .

An MCP client can launch the container as its stdio command:

{
  "mcpServers": {
    "picassoweb": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "picassoweb-mcp"]
    }
  }
}

Security defaults

• Only HTTP and HTTPS URLs are accepted.

• Embedded URL credentials are rejected.

• Localhost, private IP ranges, link-local addresses, and reserved networks are blocked by default.

• Every browser request is checked, including redirects and subresources.

• analyze_html blocks external network requests.

• Input sizes, navigation time, DOM sampling, selector matches, CSS collection, and returned HTML are bounded.

For a trusted local development site, pass "allowPrivateNetwork": true. This should remain disabled when calls can be influenced by untrusted content.

compare_replica is the one exception with a relaxed default: allowPrivateReplica defaults to true so the replica side can point at a localhost dev server or a local file, which is the normal workflow. The original URL is still fully SSRF-guarded.

Development

npm run typecheck
npm test
npm run build

The browser integration test runs when CHROME_EXECUTABLE_PATH is set. The remaining tests validate CSS token extraction, URL safeguards, session caching, and the exposed MCP contract without requiring a browser.

For a full end-to-end smoke test of the built server over real stdio (tool listing, extraction, session-cache speedup, interaction capture, motion sampling, crawling):

npm run build
node scripts/cold-test.mjs            # defaults to https://getbootstrap.com/
node scripts/cold-test.mjs https://your-target.example

Practical limitations

• Authentication, cookie consent, CAPTCHAs, and anti-bot systems are not bypassed.

• Content that appears only after a user-specific interaction may require a separate browser automation step before analysis.

• Computed styles remain available when cross-origin stylesheet rules are inaccessible. Raw CSS variables are additionally recovered from readable stylesheet responses when possible.

• Component recognition is semantic and heuristic. inspect_component provides the exact follow-up data when a family needs closer analysis.

• Downloaded assets are the original copyrighted files. Reuse them only where you have the right to; extract_assets is a copy tool, not a licensing check.

• extract_animations is a static census: its WAAPI data is a one-shot settled snapshot and its scroll-reveal data captures visible start/end values, not the exact JS timeline. capture_motion is the complementary dynamic recorder for frame strips, numeric curves, reload/entry motion, and timeline behavior over time.

• extract_layout reports stacking-context evidence, z-index, and DOM order, but does not calculate the browser's exact global paint order.

• capture_motion samples in real wall-clock time (interval floor 100 ms), so very fast animations yield few distinct frames — the per-frame numeric style curves still capture them. GSAP drives elements from its own ticker and never appears in the Web Animations API inventory; its motion shows up in the frame strip and the numeric curves instead.

• crawl_site follows a[href] links only (SPAs that navigate from click handlers need capture_interactions) and does not consult robots.txt — it is an interactive agent tool with small page caps, not a bulk crawler.

• Matched rules and forced interaction states use Chromium DevTools Protocol and are therefore Chromium-only. Elements in out-of-process frames can still return evaluate-side inspection data, but CDP-only enrichment may be omitted with a warning.

• compare_replica freezes declarative and WAAPI motion and stubs requestAnimationFrame after settling, but the rAF freeze is best-effort; canvas, video, WebGL, timers, and external data can remain nondeterministic. Run selfCheck first to measure that page's noise floor.

License

MIT