uiscanner-mcp

uiscanner-mcp

An MCP server (and CLI) that lets any agent — Claude Code, Claude Desktop, Cursor, Codex — scan a public URL and get a design teardown: design tokens + section structure + a Claude-tailored build prompt to recreate the look.

It's a thin client over the hosted uiscanner API, so it inherits the SSRF guard, rate limits, and the "describe and tokenize, never re-host asset bytes" posture.

Tools

Tool	What it does
ui_teardown({ url, target?, include_screenshot? })	Scan a page. Returns an id, a shareable uiscanner.com/t/<id> link, design tokens, section structure, and the build prompt. Takes up to ~3 minutes.
get_teardown({ id, include_screenshot? })	Fetch a finished teardown by its id or its share link. No re-scan.
retarget_teardown({ id, target })	Re-tailor the build prompt to a different archetype without re-scanning (cheaper and faster than a new scan).
whoami()	Plan and scans remaining this window. Read-only; spends no scan.

• target (optional) — landing | dashboard | marketing | ecommerce | portfolio | mobile | general (default general).
• include_screenshot (optional) — also return the rendered page as an image (larger payload, default off).

Each result comes back as a human-readable summary and a typed structuredContent object ({ id, url, domain, target, prompt, tokens, sections, brand, full_screenshot_url }) your agent can act on directly.

Install

No clone, no keys to paste — it runs straight from npm via npx. The first scan opens your browser to sign in to uiscanner (token cached at ~/.uiscanner/credentials.json); every scan runs on your uiscanner plan.

Claude Code

claude mcp add uiscanner -- npx -y uiscanner-mcp@latest

Codex — ~/.codex/config.toml

[mcp_servers.uiscanner]
command = "npx"
args = ["-y", "uiscanner-mcp@latest"]

Cursor / Claude Desktop — .cursor/mcp.json or claude_desktop_config.json

{
  "mcpServers": {
    "uiscanner": {
      "command": "npx",
      "args": ["-y", "uiscanner-mcp@latest"]
    }
  }
}

Then ask your agent: "ui_teardown stripe.com for a landing page" — it signs you in on the first call. (@latest keeps npx from reusing a stale cached build.)

CLI

The same package is a one-shot CLI — handy outside an agent or in scripts:

npx -y uiscanner-mcp@latest scan stripe.com --target landing
npx -y uiscanner-mcp@latest scan stripe.com --json > tokens.json   # raw tokens for any build step
npx -y uiscanner-mcp@latest get <id|link>                          # re-fetch a finished teardown
npx -y uiscanner-mcp@latest retarget <id|link> dashboard           # re-tailor, no re-scan
npx -y uiscanner-mcp@latest whoami                                 # plan, scans left
npx -y uiscanner-mcp@latest logout                                 # remove the cached sign-in
npx -y uiscanner-mcp@latest --help

--quiet drops the progress bar (good for CI). --play plays a dino runner while the scan polls.

Config (env)

• UISCANNER_API_URL — deployment base URL. Defaults to https://uiscanner.com; set it for a local/staging deploy.
• UISCANNER_API_KEY — for CI / headless only. Set a uix_ key to skip the browser sign-in. Interactive runs don't need it.

Plans & quota

Connecting signs you in and mints a key on your uiscanner plan — there's nothing to paste:

• Free — 5 scans per rolling 30 days.
• Indie — 100 scans per 30 days.
• Studio — 400 scans per 30 days.

Out of scans before the window resets? Upgrade your plan at uiscanner.com/billing. Run whoami any time to see your plan and how many scans remain.

Troubleshooting

• "Sign in to uiscanner to continue…" — first run only. Open the printed URL, approve in the browser, then run the command (or re-invoke the tool) again. Over MCP, the sign-in link is returned to your agent so it can show you.
• 429 / "plan quota reached" — you're out of scans for the window. Run whoami to confirm, then upgrade at /billing.
• "That URL can't be analyzed" — the page is private, blocked, or behind anti-bot protection. uiscanner only scans publicly reachable pages.
• Verify your setup — npx -y uiscanner-mcp@latest whoami should print your plan and remaining scans. If it does, the MCP is wired correctly.