Skip to main content
Glama

UserFlow MCP

Simulates real users navigating your app and delivers qualitative UX feedback. Built as an MCP server for Claude Code.

UserFlow puts itself in your user's shoes. It clicks through your app as different personas (a first-time user, a busy executive, a senior citizen, an accessibility-dependent user) and tells you where they'd get confused, frustrated, or give up. Now with auto-friction detection, Core Web Vitals, WCAG accessibility auditing, network monitoring, device emulation, and rich HTML reports with dev recommendations.

Free for Claude Pro users. No API keys, no external services. Just install and go.

Quick Start

# Install globally
npm install -g userflow-mcp

# Or use directly with npx
npx -y userflow-mcp

Add to Claude Code

In your Claude Code MCP settings:

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

Then in Claude Code:

→ "Start a user flow session on https://myapp.com as Alex"
→ "Quick scan https://myapp.com"
→ "Run an accessibility audit on this page"
→ "Compare Alex and Morgan on https://myapp.com"

Related MCP server: CanaryUsers MCP Server

What You Get

Persona-Driven UX Feedback

Step 1: Landing Page (3.2s)
  šŸ” curious
  > "Hmm, 'Supercharge your workflow' — but what does this product actually do?"
  āš ļø MEDIUM: Value prop unclear — heading doesn't explain the product
     → Rewrite heading to describe what the product does, not how it makes you feel

Step 2: Signup (12.1s)
  😐 neutral
  > "Alright, let me sign up and see..."
  šŸ›‘ HIGH: Form asks for company size during signup — feels invasive
     → Remove non-essential fields from signup, ask later during onboarding

Auto-Friction Detection

Friction is automatically detected from page metrics on every step — no manual annotation needed:

  • Performance: LCP > 2.5s, CLS > 0.1, FCP > 3s

  • Accessibility: Critical/serious axe-core violations, score < 50

  • Console: JS errors, uncaught exceptions

  • Network: Failed requests, pages > 5MB transfer

  • Content: Missing headings, 50+ interactive elements (cognitive overload), visible error messages

Core Web Vitals & Performance

| Metric | Value   | Rating |
|--------|---------|--------|
| LCP    | 1840ms  | 🟢 good |
| CLS    | 0.042   | 🟢 good |
| FCP    | 920ms   | — |
| TTFB   | 180ms   | — |
| Resources | 47 files (1,280KB) | — |

Accessibility (axe-core WCAG Audit)

Score: 82/100 | Violations: 5 (0 critical, 2 serious, 2 moderate, 1 minor)
| serious | [color-contrast] Insufficient contrast ratio | 12 nodes |
| serious | [image-alt] Missing alt text on images | 3 nodes |

Rich HTML Reports

The end_session tool generates standalone HTML reports with:

  • Executive summary — key metrics at a glance (friction score, goal status, steps, time, pages, a11y score, JS errors, failed requests)

  • Site-wide page dashboard — comparison table of all pages with LCP, CLS, a11y, requests, errors

  • Emotional journey — color-coded chart with legend, tooltips, and plain English summary

  • Step-by-step walkthrough — collapsible steps with embedded screenshots

  • Aggregated accessibility — all WCAG violations across the session, sorted by impact, with axe-core help links

  • Network overview — total requests, failures, transfer size, resource breakdown, slowest requests

  • Dev recommendations — P0/P1/P2 prioritized fixes with code examples (LCP, CLS, contrast, labels, errors, cookies, headings)

  • "Idiot summary" — plain English section explaining what's wrong the way a regular user would say it

  • Print/PDF optimized — all steps expand, sidebar hides, sections avoid page breaks

14 Tools

Step-by-Step Session Tools (Claude drives the simulation)

Tool

Description

start_session

Open browser, navigate to URL, return page snapshot with screenshot + Web Vitals + a11y score. Supports device emulation.

step

Execute an action (click, type, scroll, etc.) with smart selector fallback. Record persona thoughts and friction.

end_session

Close session, compute friction score and emotional arc, return full report (markdown or HTML).

get_page_state

Get current page state and screenshot without performing any action.

v0.3 Session Tools (new capabilities)

Tool

Description

accessibility_audit

Run WCAG 2.0 A/AA/AAA audit using axe-core. Returns score, violations, and fix links.

inspect_storage

Inspect cookies, localStorage, sessionStorage. Detects tracking cookies.

export_har

Export all network activity as HAR 1.2 log for analysis.

compare_screenshots

Pixel-level visual diff between two screenshots with overlay image.

create_persona

Build a custom persona with any trait combination.

Quick Tools (stateless)

Tool

Description

quick_scan

Fast single-page scan with screenshot and element extraction.

list_personas

Browse all 8 built-in personas with full trait definitions.

list_devices

Browse all 10 device emulation profiles.

Auto Tools (heuristic walker)

Tool

Description

auto_walk

Fast automated walk with heuristic navigation — no AI reasoning.

compare_personas_auto

Run 2-5 personas on the same URL and compare experiences.

8 Built-in Personas

Name

Description

Tech

Patience

Device

Alex

The First-Timer — never used SaaS before

Novice

Moderate

Mobile

Morgan

The Power User — developer, expects excellence

Expert

Low

Desktop

Patricia

The Senior Explorer — 68, low vision

Basic

High

Desktop

Jordan

The Busy Executive — 10 seconds to impress

Intermediate

Very Low

Mobile

Sam

The Accessibility Tester — screen reader user

Advanced

Moderate

Desktop

Riley

The Skeptical Evaluator — looking for red flags

Intermediate

Moderate

Desktop

Casey

The International User — potential language barriers

Basic

High

Mobile

Taylor

The Return Visitor — knows the app, wants efficiency

Advanced

Moderate

Desktop

10 Device Profiles

Key

Device

Viewport

Scale

iphone-14-pro

iPhone 14 Pro

393Ɨ852

3x

iphone-se

iPhone SE

375Ɨ667

2x

pixel-7

Pixel 7

412Ɨ915

2.625x

samsung-galaxy-s23

Galaxy S23

393Ɨ851

3x

galaxy-fold

Galaxy Fold

280Ɨ653

3x

ipad-pro-12-9

iPad Pro 12.9"

1024Ɨ1366

2x

ipad-mini

iPad Mini

768Ɨ1024

2x

macbook-pro-14

MacBook Pro 14"

1512Ɨ982

2x

desktop-1080p

Desktop 1080p

1920Ɨ1080

1x

desktop-1440p

Desktop 1440p

2560Ɨ1440

1x

How It Works

  1. Puppeteer opens your URL in a real browser

  2. Monitors attach before navigation — network requests, console messages, and performance observers start capturing immediately

  3. The persona engine creates a user with specific traits (tech literacy, patience, goals, device)

  4. Claude drives the simulation step-by-step using the step tool, with smart selector fallback (8 strategies: data-testid → id → aria-label → role-text → input-attr → link-href → text → CSS path)

  5. At each step, the system collects:

    • Page snapshot — interactive elements, headings, forms, errors, screenshot

    • Core Web Vitals — LCP, CLS, INP, FCP, TTFB via PerformanceObserver

    • Network summary — request count, failures, transfer size, slow requests

    • Console errors — JS errors, warnings, uncaught exceptions

    • Accessibility — axe-core WCAG audit with violation details (on initial load)

    • Storage — cookies, localStorage, sessionStorage, tracking detection (on initial load)

  6. The feedback generator compiles everything into a structured report with emotional journey, friction scores, Web Vitals, and recommendations

Architecture

src/
ā”œā”€ā”€ server.ts                  # MCP tool registrations (14 tools)
ā”œā”€ā”€ types.ts                   # Full type system (450+ lines)
ā”œā”€ā”€ personas/
│   ā”œā”€ā”€ presets.ts             # 8 built-in personas
│   └── engine.ts              # Persona creation + resolution
ā”œā”€ā”€ session/
│   ā”œā”€ā”€ types.ts               # LiveSession with monitors
│   └── session-manager.ts     # Session lifecycle + new audit methods
ā”œā”€ā”€ walker/
│   ā”œā”€ā”€ flow-walker.ts         # Autonomous page traversal
│   ā”œā”€ā”€ action-planner.ts      # Heuristic action decisions
│   └── session-recorder.ts    # Journey tracking
ā”œā”€ā”€ analysis/
│   ā”œā”€ā”€ friction.ts            # Friction detection + scoring
│   ā”œā”€ā”€ cognitive-load.ts      # Page complexity assessment
│   ā”œā”€ā”€ clarity.ts             # CTA + value prop evaluation
│   └── emotional-arc.ts       # Sentiment tracking
ā”œā”€ā”€ feedback/
│   ā”œā”€ā”€ generator.ts           # Markdown report (with Web Vitals, a11y, network)
│   ā”œā”€ā”€ html-report.ts         # Rich standalone HTML report
│   ā”œā”€ā”€ comparison.ts          # Multi-persona comparison
│   └── report.ts              # Legacy report utilities
└── utils/
    ā”œā”€ā”€ browser.ts             # Puppeteer + CDP connection support
    ā”œā”€ā”€ page-snapshot.ts       # Full page state extraction + v0.3 enrichment
    ā”œā”€ā”€ actions.ts             # Action execution with smart selector fallback
    ā”œā”€ā”€ selector-engine.ts     # 8-strategy smart selector generation
    ā”œā”€ā”€ auto-friction.ts       # Auto-detect friction from page metrics
    ā”œā”€ā”€ network-monitor.ts     # Request/response tracking + HAR export
    ā”œā”€ā”€ console-monitor.ts     # Console message + page error capture
    ā”œā”€ā”€ performance.ts         # Core Web Vitals via PerformanceObserver
    ā”œā”€ā”€ accessibility.ts       # axe-core WCAG audit
    ā”œā”€ā”€ device-profiles.ts     # 10 device emulation presets
    ā”œā”€ā”€ storage-inspector.ts   # Cookie/localStorage inspection
    └── screenshot-diff.ts     # Pixel-level visual comparison

Requirements

  • Node.js >= 18.0.0

  • Google Chrome or Chromium installed

  • Claude Code with MCP support

Development

git clone https://github.com/prembobby39-gif/userflow-mcp.git
cd userflow-mcp
npm install
npm run build     # compiles TypeScript to dist/
npm test          # 42 tests
npm start         # run the MCP server

Note for contributors: You must run npm run build after cloning — the dist/ directory is not committed to git. Requires Node.js >= 18 and Google Chrome installed.

Changelog

v0.3.1

  • Auto-friction detection — automatically detects friction from page metrics (performance thresholds, a11y violations, console errors, network failures, layout issues, visible errors). Runs on every step and initial page load.

  • Executive summary — key metrics at a glance in HTML reports

  • Site-wide page dashboard — comparison table showing all pages side-by-side with LCP, CLS, a11y, violations, requests, errors

  • Aggregated accessibility section — all violations across the session, sorted by impact, with axe-core help links

  • Network overview — total requests, failures, transfer size, resource breakdown, slowest requests

  • Dev recommendations — P0/P1/P2 prioritized actionable fixes with code examples

  • "Idiot summary" — plain English section explaining what's wrong the way a regular user would say it

  • Emotional journey improvements — color legend, descriptive tooltips, plain English summary

  • Sidebar navigation — fixed left sidebar with jump links, highlights on scroll

  • Collapsed steps — steps start collapsed with expand/collapse all buttons

  • Screenshot compression — CSS max-height + object-fit for embedded screenshots

  • Print/PDF optimization — all steps expand, sidebar hides, sections avoid page breaks

v0.3.0

  • Smart selector engine with 8-strategy fallback chain

  • Console capture (JS errors, warnings, uncaught exceptions)

  • Network monitoring with HAR 1.2 export

  • Accessibility auditing via axe-core (WCAG 2.0 A/AA/AAA)

  • Core Web Vitals (LCP, CLS, INP, FCP, TTFB)

  • Device emulation (10 profiles: iPhone, Pixel, iPad, Galaxy Fold, desktops)

  • Cookie/localStorage/sessionStorage inspection with tracking detection

  • Screenshot visual diffing via pixelmatch

  • Rich standalone HTML reports with embedded screenshots

  • Custom persona creation tool

  • 6 new tools, 3 enhanced tools (14 total)

v0.2.1

  • CDP connection support for testing logged-in sites (CHROME_CDP_URL, CHROME_WS_ENDPOINT)

v0.2.0

  • Thin MCP architecture — Claude drives step-by-step simulation

  • 8 built-in personas with full trait system

v0.1.0

  • Initial release with autonomous heuristic walker

License

MIT — ARISTONE

Available Tools

14 tools
accessibility_auditA

Run a WCAG accessibility audit on the current page of a session using axe-core. Returns a score (0-100), all violations with WCAG criteria, and actionable fixes.

Inputs: session_id (required), wcag_level.

auto_walkA

Fast automated walk using heuristic-based navigation (no AI reasoning). Runs the full flow autonomously and returns a report. Use this for quick scans when you don't need to drive step-by-step.

Inputs: url (required), persona (required), max_steps.

compare_personas_autoA

Run the automated heuristic walker for multiple personas on the same URL and compare their experiences. Fast but less nuanced than step-by-step simulation.

Inputs: url (required), personas (required), max_steps.

compare_screenshotsA

Compare two base64 PNG screenshots pixel-by-pixel. Returns match percentage and a visual diff image highlighting differences. Useful for detecting UI regressions or verifying changes.

Inputs: screenshot1 (required), screenshot2 (required), threshold.

create_personaA

Create a custom persona for testing. Define their name, goals, tech literacy, patience, device preference, and accessibility needs. Returns the persona definition to use with start_session.

Inputs: name (required), goals (required), description (required), device, +6 more.

end_sessionA

End a session and get the final report. Closes the browser, computes friction score and emotional arc, and returns the full session transcript with all recorded thoughts, friction points, and recommendations.

v0.3: Report now includes Core Web Vitals, accessibility score, network summary, and console errors.

Inputs: session_id (required), format, summary, goal_achieved.

export_harA

Export all network requests captured during the session as a HAR 1.2 log. Useful for analyzing network performance, finding slow requests, and debugging API calls.

Inputs: session_id (required).

get_page_stateA

Get the current page state and screenshot without performing any action. Useful for re-examining the page or checking if lazy-loaded content has appeared.

Inputs: session_id (required), full_page.

inspect_storageA

Inspect cookies, localStorage, and sessionStorage for the current page. Identifies tracking cookies and calculates total cookie size.

Inputs: session_id (required).

list_devicesA

List all available device emulation profiles (phones, tablets, desktops). Use the device key with start_session's device_profile parameter.

Inputs: no named parameters.

list_personasA

List all built-in personas with their full trait definitions. Use this to choose a persona for start_session, or to understand each persona before roleplaying as them.

Inputs: no named parameters.

quick_scanA

Fast single-page scan. Navigates to the URL, captures a screenshot, extracts all interactive elements, headings, forms, and error messages. Returns everything to you for analysis — no session state required.

Inputs: url (required), wait_ms, full_page, viewport_width, +1 more.

start_sessionA

Start a user flow session. Opens a browser, navigates to the URL, and returns the first page snapshot with a screenshot plus Core Web Vitals, accessibility score, and network summary. Claude then drives the simulation step-by-step using the "step" tool, roleplaying as the persona.

Workflow: start_session → step (repeat) → end_session

The persona definition is returned so you can roleplay as them — adopt their tech literacy, patience, goals, and behavioral patterns when deciding what to click next.

v0.3: Supports device emulation via device_profile parameter. Use list_devices to see all options.

Inputs: url (required), persona, device_profile, viewport_width, +1 more.

stepA

Execute one step in a session. Tell the MCP what action to take (click, type, scroll, etc.) and optionally record your persona thoughts, emotional state, and any friction you noticed. Returns the resulting page state with a new screenshot.

Actions: click, type, scroll, scroll_up, navigate, select, hover, press_key, wait

v0.3: Smart selector fallback — if your CSS selector fails, the engine will try alternative strategies (data-testid, aria-label, text content) automatically.

Inputs: action (required), session_id (required), value, target, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools have distinct purposes: session control (start/step/end), observation (get_page_state), analysis (accessibility_audit, inspect_storage, export_har, compare_screenshots), and persona/device management. The only possible confusion is between start_session and quick_scan, both navigate but one establishes a session; descriptions clarify this. Overall, tools are well-differentiated.

    Naming Consistency3/5

    Tool names are predominantly verb_noun (start_session, get_page_state, create_persona), but some deviate with adjective_noun or single-word names (quick_scan, auto_walk, step). All use snake_case, which maintains readability, but the inconsistency in grammatical pattern reduces predictability.

    Tool Count4/5

    14 tools cover the full user flow testing lifecycle without feeling bloated. Each tool addresses a specific concern: session control, page inspection, accessibility, storage/network analysis, persona management, and automated comparisons. The count is appropriate for the comprehensive feature set.

    Completeness4/5

    The tool surface covers the core lifecycle (start/step/end), plus useful extensions like accessibility audits, storage/HAR inspection, and persona-based automated testing. Minor gaps exist (no update/delete persona, no resize viewport beyond device profiles), but they don't hinder the primary use case. Overall, the domain is well-covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI coding agents to drive a real browser like a person — crawling every page and role, running real user journeys, and auditing controls a DOM-based test misses — so UI, accessibility and permission bugs are found and only the screens affected by recent changes are re-tested. Runs are script-driven and read-only by default, so testing costs no model tokens and nothing about the app is sent to an AI.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to measure live web and responsive UIs — contrast ratios, touch-target sizes, overflow, and theme drift — and return precise findings as text with element selectors, rather than relying on screenshot guesses. Also lets an agent navigate, tap, type, and scroll in shared mobile and desktop sessions that a human watches in the same live panel and can annotate with pinned notes.
      95 npm
      MIT