UserFlow MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@UserFlow MCP Quick scan https://myapp.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpAdd 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 onboardingAuto-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
Puppeteer opens your URL in a real browser
Monitors attach before navigation ā network requests, console messages, and performance observers start capturing immediately
The persona engine creates a user with specific traits (tech literacy, patience, goals, device)
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)
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)
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 comparisonRequirements
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 serverNote for contributors: You must run
npm run buildafter cloning ā thedist/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 toolsaccessibility_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
Scored across 14 tools
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.
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.
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.
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
Related MCP Connectors
Deploy AI user personas to validate user journeys at scale. Find UX friction before real users do.
AI personas test your site like real users and return scored reports with fix prompts.
A flock of AI users tests your deployed app and reports where real people get stuck, with fixes.
AI users run real tasks on your live site and show where they get stuck, with a replay of every step
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceDeploys AI user personas to validate user journeys at scale, surfacing UX friction before real users encounter it.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to scan deployed web apps by sending a flock of AI users that identify UX issues, mobile breakage, and conversion path problems, returning prioritized, fix-ready findings.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT