Copycat MCP

Copycat gives your coding agent a place to keep design references.

Point an MCP client at a site, give it an alias, and Copycat saves the screenshots and evidence an agent needs to describe the style: structure, links, CSS variables, computed styles, notes, design guidance, and config. Later, the agent can pull that profile back by name and use it as direction for new UI.

This avoids your agent reinventing the wheel on every new project. The agent can inspect a saved profile instead of relying on a one-time page description from an old session.

Before and after

Copycat captures a site's visual system, then lets an agent reuse that direction for original UI work.

Original site	With Copycat

How it works

A typical capture can start with one sentence:

1. You say: Save https://linear.app as linear.
2. Your MCP client routes the request to Copycat, and the agent calls create to create ~/.copycat/designs/linear/.
3. The agent captures Linear with Playwright: screenshots plus combined page evidence (structure, links, CSS variables, computed styles).
4. The agent writes DESIGN.md, config.json, and notes.md on disk under the alias paths, and updates metadata.json pages for sampled URLs.
5. Later, you can say Use linear as visual direction for this settings page, and the agent can read the saved profile with get instead of starting over.

Each alias is isolated on disk. A profile for linear lives at ~/.copycat/designs/linear/, and its screenshots stay inside that folder.

Install

Install the MCP server & Playwright Browser:

uv tool install copycat-mcp
uvx --from playwright playwright install chromium

Connect an MCP client

Use the installed copycat-mcp executable in your MCP client config.

{
  "mcpServers": {
    "copycat": {
      "command": "copycat-mcp"
    }
  }
}

For opencode:

{
  "mcp": {
    "copycat": {
      "type": "local",
      "command": ["copycat-mcp"],
      "enabled": true
    }
  }
}

Restart your MCP client after changing MCP config.

Agent guide

Call guide at the start of capture or apply work. It returns the bundled markdown workflow for sampling pages, capturing evidence, authoring DESIGN.md, applying a profile, and legal boundaries.

Capture tools take a slug name only and write under screenshots/<name>.png or evidence/<name>.json. Authored profile files (DESIGN.md, config.json, notes.md, metadata.json pages) are written by the agent on disk using paths from create / get.

Try it

Ask your MCP-aware coding agent for the result you want. You usually do not need to call the tools by hand.

Capture https://vercel.com as a Copycat profile named vercel.
Call guide first, then capture desktop and mobile screenshots and evidence,
sample 5-10 representative public pages when available, and write a substantial
agent-authored DESIGN.md (~180-220 lines) with colors, typography, spacing,
layout patterns, component states, caveats.

List my saved Copycat profiles and tell me which one fits a clean B2B SaaS
settings page.

Use the vercel Copycat profile as visual direction for a billing settings page
in this app. Do not copy assets or text. Reuse the spacing, type scale, color
behavior, and component rhythm.

Open the vercel Copycat profile and summarize the design config I should use
for a pricing page.

If your client exposes raw tools, the usual capture flow is:

create
capture_screenshot
capture_page
# then agent writes DESIGN.md, config.json, notes.md, metadata.pages on disk

What gets saved

Copycat writes each profile under:

~/.copycat/designs/<alias>/

The important files are:

DESIGN.md       Agent-authored human-readable design guidance
config.json     Structured colors, type, spacing, radii, shadows, and other style values
notes.md        Additional observations or agent notes
metadata.json   alias, sourceUrl, createdAt, lastUpdated, pages
screenshots/    Captured desktop and mobile screenshots
evidence/       Combined page evidence (structure, links, CSS variables, computed styles)

Storage location

By default, Copycat stores profiles in:

~/.copycat/designs

Set COPYCAT_ROOT to use a different design library root.

Development

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m playwright install chromium

Run validation:

.venv/bin/python -m pytest
.venv/bin/python -m mypy

Verify the package installs as a persistent tool:

uv tool install .
uv tool list