UIMax MCP

UIMax MCP

Turns Claude Code into a frontend expert that reviews and fixes your UI automatically.

One command — "review my UI at localhost:3000" — and it:

1. Sees your app — captures a real screenshot via Puppeteer
2. Audits accessibility — runs axe-core for WCAG 2.1 violations
3. Runs Lighthouse — real Google Lighthouse scores (Performance, Accessibility, Best Practices, SEO)
4. Measures performance — captures Core Web Vitals (FCP, LCP, CLS, TBT)
5. Scans your code — checks for 25+ anti-patterns across accessibility, design, and code quality
6. Generates an expert review — Claude acts as a senior frontend engineer with a baked-in review methodology
7. Implements the fixes — edits your actual code files, starting from critical issues down

Free for all Claude Code users (Pro plan and above). No API keys. No extra costs. Just install and go.

claude mcp add uimax -- npx -y uimax-mcp

The Problem

You're building a frontend. You want expert-level feedback on your UI — visual design, accessibility, performance, code quality. Normally you'd need to:

1. Take screenshots manually
2. Run Lighthouse / axe separately
3. Review your own code with fresh eyes
4. Compile all findings into a coherent review
5. Then figure out the fixes

That's 5 steps too many.

Quick Start

Install as MCP Server (for Claude Code)

# Add to Claude Code — that's it, no API keys needed
claude mcp add uimax -- npx -y uimax-mcp

That's it. Now in any Claude Code conversation:

You: Review the UI at http://localhost:3000, source code is in ./src

Claude Code calls review_ui ->
  1. Captures screenshot of your running app
  2. Runs axe-core accessibility audit
  3. Runs Google Lighthouse (Performance, A11y, Best Practices, SEO)
  4. Measures Core Web Vitals
  5. Scans source code for 25+ anti-patterns
  6. Returns screenshot + all data + expert review methodology
  7. Claude Code generates expert review (using YOUR Pro plan -- $0 extra)
  8. Claude Code implements every fix automatically

Install Globally

npm install -g uimax-mcp

Tools

The MCP server exposes 12 tools that Claude uses automatically:

review_ui -- Full Automated Pipeline

This is the main tool. One call does everything:

1. Captures screenshot of your running app
2. Runs accessibility audit (axe-core WCAG 2.1)
3. Runs Google Lighthouse (scores + key audits)
4. Measures Core Web Vitals via Performance API
5. Scans your source code for anti-patterns
6. Returns ALL data + expert frontend review methodology to Claude Code
7. Claude Code generates the expert review and implements fixes

Input:  URL + code directory
Output: Screenshot + Lighthouse scores + audit data + expert methodology
        -> Claude Code generates review + implements every fix

100% free for Pro plan users. The MCP handles data collection. Claude Code (your existing subscription) handles the expert review and implementation. No API keys. No extra charges.

quick_review

Fast design-only review. Captures a screenshot and returns it with a focused design methodology. No code analysis, no performance audit. Good for rapid iteration.

lighthouse_audit

Runs a full Google Lighthouse audit and returns real scores for:

• Performance (0-100)
• Accessibility (0-100)
• Best Practices (0-100)
• SEO (0-100)

Plus detailed findings for failing audits with fix instructions. This is the real Lighthouse — the same tool Chrome DevTools uses.

compare_screenshots

Before/after visual comparison. Give it two URLs — captures both, returns them side by side with a difference percentage. Perfect for:

• Verifying UI fixes actually changed what you expected
• Comparing staging vs production
• Visual regression checking

Input:  URL A ("before") + URL B ("after")
Output: Both screenshots + difference percentage + metadata

export_report

Generates a standalone HTML report with everything embedded — screenshot, accessibility violations, Lighthouse scores, performance metrics, code findings. Dark themed, zero external dependencies. Share it with your team, attach it to a PR, or email it to a client.

Input:  URL + code directory + output path (optional)
Output: Self-contained HTML file at the specified path

screenshot

Captures a high-resolution PNG screenshot of any URL. Claude can see the image directly and analyze visual design, layout, spacing, typography, and color usage.

responsive_screenshots

Captures screenshots at mobile (375px), tablet (768px), and desktop (1440px) viewports. Perfect for reviewing responsive design.

check_dark_mode

Detects whether your app supports dark mode. Captures two screenshots — light mode and dark mode (emulated via prefers-color-scheme: dark) — and compares them. Returns both screenshots + a difference percentage.

accessibility_audit

Injects axe-core into the page and runs a WCAG 2.1 Level A & AA audit. Returns violations grouped by severity with fix instructions.

performance_audit

Measures Core Web Vitals using the browser's Performance API:

• First Contentful Paint (FCP)
• Largest Contentful Paint (LCP)
• Cumulative Layout Shift (CLS)
• Total Blocking Time (TBT)
• DOM node count, resource count, JS heap size

analyze_code

Scans frontend source files for 25+ categories of issues. Supports custom configuration via .uimaxrc.json (see Configuration).

Configuration

Create a .uimaxrc.json in your project root to customize code analysis:

{
  "rules": {
    "console-log": "off",
    "magic-number": "off",
    "hardcoded-color": "warn",
    "inline-style": "error"
  },
  "severity": {
    "todo-fixme": "high"
  },
  "ignore": [
    "node_modules",
    "dist",
    "*.test.*",
    "*.spec.*"
  ]
}

• rules — Set any rule to "off", "warn", or "error"
• severity — Override severity: "low", "medium", "high", "critical"
• ignore — Additional glob patterns to exclude from analysis

UIMax searches for .uimaxrc.json in the target directory and up to 3 parent directories, so it works in monorepos.

Prompts

Expert review prompts that guide Claude's analysis:

Example Workflows

Full Review (the main workflow)

You: Review the UI at http://localhost:3000
     Source code is in /Users/me/project/src

Claude: [Calls review_ui]
        [Captures screenshot, runs Lighthouse + axe + perf + code scan]
        [Generates 20+ findings with specific fixes]
        [Implements every fix automatically]

Before/After Comparison

You: Compare localhost:3000 with localhost:3001

Claude: [Calls compare_screenshots]
        [Shows both screenshots side by side]
        [Reports 23% visual difference]
        [Identifies what changed]

Generate Shareable Report

You: Export a full report of localhost:3000 to ./report.html

Claude: [Calls export_report]
        [Runs all audits, generates standalone HTML]
        [Saves to ./report.html — open in any browser]

Lighthouse Scores

You: Run Lighthouse on http://localhost:3000

Claude: [Calls lighthouse_audit]
        [Returns Performance: 92, Accessibility: 87, Best Practices: 100, SEO: 90]
        [Lists failing audits with fix instructions]

Responsive Check

You: Check if my site is responsive - http://localhost:3000

Claude: [Calls responsive_screenshots]
        [Shows mobile, tablet, desktop views]
        [Identifies layout issues at each breakpoint]

Quick Design Feedback

You: Take a screenshot of localhost:3000 and tell me
     what a senior designer would change

Claude: [Calls quick_review]
        [Provides focused design feedback + implements fixes]

Accessibility Only

You: Run an accessibility audit on http://localhost:3000

Claude: [Calls accessibility_audit]
        [Reports WCAG violations with fix instructions]

What Claude Reviews

When using the full review_ui pipeline, Claude evaluates:

Code Analysis Rules

The analyze_code tool checks for 25+ rules across categories:

All rules can be toggled via .uimaxrc.json.

Supported Frameworks

Auto-detected from package.json:

• React / Next.js
• Vue / Nuxt
• Svelte / SvelteKit
• Angular
• Plain HTML/CSS/JS

Requirements

• Node.js >= 18.0.0
• Chrome/Chromium (uses your system Chrome — no extra download)
• Claude Code (for MCP integration)
• No API keys needed — runs entirely within Claude Code using your existing Pro plan

How It Works

+------------------------------------------------------------------+
|                  Claude Code (your Pro plan)                       |
|                                                                   |
|  User: "Review my UI at localhost:3000 and fix everything"        |
|           |                                                       |
|           v                                                       |
|  +------------------------------------------------------------+  |
|  |              UIMax MCP (data collection)                    |  |
|  |                                                             |  |
|  |  Screenshot -----> Puppeteer -------> PNG Image             |  |
|  |  Accessibility --> axe-core --------> WCAG Violations       |  |
|  |  Lighthouse -----> Google LH -------> Scores + Audits      |  |
|  |  Performance ----> Perf API --------> Web Vitals            |  |
|  |  Code Scan ------> File Analysis ---> Anti-patterns         |  |
|  |  Expert Prompt --> Baked-in methodology                     |  |
|  +-------------------------+----------------------------------+   |
|                            |                                      |
|                            v                                      |
|  Claude Code receives: screenshot + data + expert methodology     |
|                            |                                      |
|                            v                                      |
|  Claude acts as world-class frontend expert (FREE -- Pro plan)    |
|     Generates comprehensive review with exact fixes               |
|                            |                                      |
|                            v                                      |
|  Claude implements every fix in the codebase automatically        |
|                                                                   |
+------------------------------------------------------------------+

Development

# Clone
git clone https://github.com/prembobby39-gif/uimax-mcp.git
cd uimax-mcp

# Install
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Test locally with Claude Code
claude mcp add uimax-dev -- node /path/to/uimax-mcp/dist/index.js

Contributing

Contributions welcome! Some ideas:

• CSS specificity analyzer
• Design token extraction
• Framework-specific checks (Vue composition API, Svelte stores)
• Visual regression with pixel-level diffing
• Performance budgets (fail if bundle > X KB)
• Custom rule plugins (user-defined regex rules)
• Figma design comparison (screenshot vs Figma mock)

License

MIT