red-design-mcp

Give your AI tools a designer's eye.

Analyze, recreate, reimagine, critique and audit any design straight from Claude Code, Codex, Cursor and every other MCP client.

Quick start · Tools · Examples · How it works · Roadmap

Why red-design-mcp?

Quick start

npx red-design-mcp install

That's it. The installer detects Claude Code, Codex, Cursor and Claude Desktop, adds the server, backs up any config it edits (.bak), and never touches your other servers. Restart your AI tool and try:

"Analyze ./screens/pricing.png and recreate it in Tailwind."

npx red-design-mcp install                    # auto-detect your tools
npx red-design-mcp install --client codex,cursor
npx red-design-mcp install --all              # every supported client
npx red-design-mcp install --print            # just show the config snippets
npx red-design-mcp doctor                     # check Node, mode and detected clients
npx red-design-mcp doctor --check             # also confirm your model still exists
npx red-design-mcp agents                     # install 13 design agents for your AI tools

claude mcp add --scope user red -- npx -y red-design-mcp

[mcp_servers.red]
command = "npx"
args = ["-y", "red-design-mcp"]

{
  "mcpServers": {
    "red": { "command": "npx", "args": ["-y", "red-design-mcp"] }
  }
}

Tools

Vision tools

These look at an image. They run in host or API-key mode.

Autonomous audit

Web tools

These work on live websites.

Deterministic tools

These never need a model or a key. Same input, same answer, instantly.

Agents

red-design-mcp ships agents on three levels, so you pick how much to delegate.

1. Workflow prompts (any MCP client)

Seven ready-made playbooks that tell your AI exactly which tools to run, in order, and how to report. In Claude Code they appear as slash commands such as /mcp__red__redesign.

2. Specialist agents for every major AI coding tool

Every tool has its own agent format, so one command writes each agent in the native format of the tools you use. There are 13 agents: 12 specialists for specific tasks, plus a design lead that handles everything else.

npx red-design-mcp agents                      # install into the tools it detects
npx red-design-mcp agents --target claude,codex
npx red-design-mcp agents --all                # every supported tool
npx red-design-mcp agents --project            # into this project instead of your home folder
npx red-design-mcp agents --only red-design-lead,red-css-polisher
npx red-design-mcp agents --list               # see every agent

Existing files are never overwritten unless you pass --force, and replaced files are backed up as .bak.

The AGENTS.md block is wrapped in markers, so running the command again refreshes it in place and never touches the rest of your file.

Specialists, each for one kind of task

The design lead, for everything else. red-design-lead is the generalist. It classifies the task and picks the right specialist. For multi-part work it chains them in a sensible order (extract, then system, then components, then accessibility, then originality). If your tool supports subagents it delegates by name. If not, it follows that specialist's process itself.

All agents inherit your tools, so they work with RED_TOOLS=auto too: they call find_tools and run_tool when the full tool list is not loaded.

3. Autonomous audit

audit_site is an agent in a single tool call: it runs the whole pipeline itself and returns one scored report.

One call, a whole design system

Generate a design system for #2563eb, editorial mood, round corners.

You get one paste-ready stylesheet: font @import, light and dark themes, color scales, fluid type, spacing, radii, shadows and accessible base styles, plus a verified checklist:

✓ Light: text on background: 13.03:1 (needs 4.5:1)
✓ Light: button label on primary: 5.17:1 (needs 4.5:1)
✓ Dark:  muted text on surface: 5.01:1 (needs 4.5:1)
✓ Dark:  primary on background (UI): 4.67:1 (needs 3:1)

Reverse-engineer any website

Extract the design tokens from https://example.com and lint its CSS.

Capture https://example.com on mobile, then recreate it in Tailwind and fix its accessibility problems.

Typical flow: extract_css_tokens (exact values from the CSS) → capture_url (what it looks like) → recreate or reimagine → audit_accessibility → originality_check.

Some sites style themselves with JavaScript, so their CSS is not in the page. For those, capture_url plus the vision tools still works.

Example prompts

Analyze ./checkout.png and recreate it as a responsive Tailwind page.

Reimagine this dashboard as brutalist, dial 80, and give me 3 variations.

Take the layout of ./a.png and the mood of ./b.png and build it in React.

Audit ./signup.png for accessibility, then fix every failing color in my code.

Generate a triadic palette from #e11d48 as a Tailwind config.

Do my status colors work for color-blind users? error #d32f2f, success #2e7d32.

Create a fluid type scale: 16px base, perfect fourth.

Compare the tokens of the original and my version. Is it too similar?

Turn ./hero.png into a prompt I can paste into v0.

Compare ./mine.png with ./reference.png and tell me how to make them match.

Make a dark theme from my tokens and fix any contrast problems.

Suggest font pairings for a luxury skincare brand.

Check every text and background combination in my brand colors.

Give me accessible button styles for #7c3aed with every state.

Make a smooth gradient from #e11d48 to #0ea5e9. Can I put white text on it?

Lint this CSS and tell me what to fix first.

The inspiration dial

reimagine takes a dial from 0 to 100.

Presets: minimal · brutalist · glassmorphism · neumorphism · retro-futuristic · editorial · playful · luxury · dark-mode · high-contrast, or describe your own ("90s arcade meets Swiss design").

Two modes

Supported providers

The defaults are the current balanced, image-capable models, checked against each provider's documentation on October 31, 2026. Providers rename and retire models often, so set RED_MODEL to use a different one (for example a larger model like claude-opus-5-5, or an evergreen alias such as gemini-flash-latest or ~anthropic/claude-sonnet-latest on OpenRouter), and run npx red-design-mcp doctor --check to confirm your model still exists. For the vision tools the model must accept images. If several keys are set, the first match in the order above wins, or force one with RED_PROVIDER (anthropic, openai, google, groq, openrouter or custom). A custom endpoint always wins when RED_BASE_URL is set.

{
  "mcpServers": {
    "red": {
      "command": "npx",
      "args": ["-y", "red-design-mcp"],
      "env": { "GROQ_API_KEY": "your-key" }
    }
  }
}

Local model with Ollama (no key needed):

"env": { "RED_BASE_URL": "http://localhost:11434/v1", "RED_MODEL": "llava" }

Claude Code: claude mcp add --scope user -e GEMINI_API_KEY=your-key red -- npx -y red-design-mcp

npx red-design-mcp doctor shows which provider and model are active, and doctor --check asks the provider whether that model is still available. Requests that hit a rate limit or a temporary server error are retried once automatically.

Choosing tools

red-design-mcp has 31 tools. Loading all of them is the default, but you can control what your AI sees, or let the AI choose for itself. Set RED_TOOLS in your client's env.

Groups: core (the 9 essentials), vision, web, color, system, components, quality. Combine groups with commas and exclude a tool with a dash.

{
  "mcpServers": {
    "red": {
      "command": "npx",
      "args": ["-y", "red-design-mcp"],
      "env": { "RED_TOOLS": "auto" }
    }
  }
}

How auto works

1. The AI calls find_tools with a plain description, such as "check a website's accessibility".
2. It gets the best matches with each tool's parameters.
3. It calls run_tool with the tool name and arguments.

This works in every MCP client, because it does not depend on the client refreshing its tool list. The trade-offs are one extra step per task and arguments passed as a JSON object. Matching is keyword based and tuned for this toolset.

npx red-design-mcp doctor shows how many tools load directly. The agent workflows chain many tools, so they work best with all or auto.

How it works

1. You share a design (an image, a URL or CSS) with your AI tool.
2. Your AI calls the tools it needs over MCP.
3. Results come back. Exact tools return their results directly. Vision tools hand the image and instructions back to your AI tool (host mode, the default), or ask a vision model themselves when you set a provider key.
4. You get code, tokens or reports.

Exact tools never call a model: contrast, palettes, scales and audits are computed in code, so results are repeatable.

A typical flow chains the tools: analyze_design → extract_tokens → reimagine → audit_accessibility → originality_check.

Responsible use

red-design-mcp is built to learn from structure and style, not to copy someone's brand. Recreations use neutral placeholders instead of logos or trademarked artwork, and originality_check helps you confirm your result is genuinely your own. It compares tokens only (not layout or content) and is not legal advice.

Roadmap

• Analyze, recreate and reimagine with dial, remix and variations
• Design tokens to CSS, Tailwind, W3C and Figma (Tokens Studio)
• WCAG audit, contrast math and color-blindness simulation
• Palette generator, fluid type scales and originality check
• One-command installer and API-key-free host mode
• Multiple model providers: Anthropic, OpenAI, Gemini, Groq, OpenRouter and any OpenAI-compatible endpoint
• Complete design-system generator with light and dark themes
• Agent workflows, 13 specialist agents for five AI tools plus AGENTS.md, and an autonomous site audit
• Capture screenshots from a URL and extract tokens from live CSS
• CSS design linter
• Generate real Figma frames through the Figma API
• Hosted HTTP/SSE transport for web clients
• Visual diff between a design and its recreation
• Storybook and component-library export
• Multi-page site crawl for full design-system extraction

Contributing

Contributions are welcome. Open an issue to discuss an idea, or send a PR:

git clone <your-fork-url> && cd red-design-mcp
npm install
npm test          # builds, then runs the automated tests
npm run inspect   # opens the MCP Inspector against your build

Please keep new deterministic tools dependency-free and add a short example prompt to this README.

License

MIT © red-design-mcp contributors