How do I use pagelens?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pagelens screenshot the page and get console logs" 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.

pagelens

by amoghmanral

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

PageLens

MCP server that gives AI coding agents visual feedback on frontend apps. One command, no config — your AI agent can now see your app, click buttons, read console errors, and diff visual changes.

npx pagelens http://localhost:3000

The Problem

When using AI coding agents (Claude Code, Cursor, Windsurf) for frontend development, the agent is blind. It can edit code but can't see what the app looks like. This creates a painful manual loop:

Agent makes a code change
You look at the browser
You describe the visual issue in words, or screenshot and drag into chat
You copy console errors manually
Repeat dozens of times per session

PageLens eliminates this loop entirely.

Related MCP server: websight

How It Works

Your app (localhost:3000)
        |
Headless Chrome (Puppeteer)
        |
PageLens MCP Server
        |
Claude Code / Cursor / Windsurf

PageLens launches a headless browser pointed at your dev server, collects console logs and network errors passively, and exposes tools that any MCP-compatible AI agent can call — screenshots, clicking, typing, DOM inspection, visual diffing — without you doing anything manually.

Why PageLens over Playwright MCP / Browser MCP?

General-purpose browser automation MCPs expose low-level primitives — you get evaluate JavaScript, take screenshot, click element as separate, disconnected actions. PageLens is purpose-built for the AI frontend development loop, which changes the design in ways that matter:

	PageLens	General browser MCPs
Setup	`npx pagelens <url>` — zero config	Requires browser launch management, connection handling
Console/network errors	Collected passively in the background. Agent checks whenever it wants.	Agent must actively poll or set up listeners. Errors between tool calls are lost.
Interaction feedback	Every `click`, `type`, `navigate` automatically returns a screenshot	Agent must remember to take a screenshot after each action
Visual regression	Built-in `visual_diff` — baseline capture, pixel comparison, diff image, change percentage	Not available. Agent would need to screenshot, store, compare manually.
Visual quality review	`visual_audit` returns a structured checklist that prompts the agent to critically evaluate layout, contrast, content accuracy	No equivalent. Agents tend to superficially confirm "looks good" without guidance.
Live debugging	`toggle_headless` to pop open Chrome and watch the agent work in real time	Typically headless-only or requires restart
Multi-route audit	`multi_route_screenshot` captures multiple pages in one call	Agent must navigate and screenshot each route individually

PageLens doesn't try to be a general browser automation framework. It does one thing — give your AI coding agent eyes on your frontend — and removes every manual step from that loop.

Quick Start

1. Start your dev server

npm run dev
# App running at http://localhost:5173

2. Add PageLens to your MCP config

Note: PageLens isn't on npm yet. See the Development section to install from source, then use the config below with the local path.

Claude Code (.mcp.json in project root):

{
  "mcpServers": {
    "pagelens": {
      "command": "node",
      "args": ["/path/to/PageLens/dist/index.js", "http://localhost:5173"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "pagelens": {
      "command": "node",
      "args": ["/path/to/PageLens/dist/index.js", "http://localhost:5173"]
    }
  }
}

3. Start your agent

That's it. The agent now has access to all PageLens tools. Ask it to "take a screenshot of my app" or "check for console errors" and it just works.

Tools

Observation

Tool	Description
`screenshot`	Capture the current page as PNG. Optional `route` to navigate first, `fullPage` for entire scrollable page.
`screenshot_element`	Screenshot a specific DOM element by CSS selector.
`console_logs`	Returns all console output (log, warn, error) since last call. Clears buffer after returning.
`network_errors`	Returns all failed network requests since last call. Clears buffer after returning.
`visual_audit`	Screenshot with a guided checklist prompting the agent to critically assess content accuracy, layout, contrast, and polish — not just confirm things render.

Interaction

Tool	Description
`click`	Click an element by selector. Returns screenshot after click.
`type`	Type text into an input field. Optional `clear` to replace existing content. Returns screenshot.
`scroll`	Scroll the page or a specific element up/down by a given number of pixels. Returns screenshot.
`hover`	Hover over an element by selector to trigger tooltips, dropdowns, or hover styles. Returns screenshot.
`select`	Select an option from a `<select>` dropdown by value. Returns screenshot.
`navigate`	Go to a URL or path. Returns screenshot of the new page.
`set_viewport`	Resize to a preset (`mobile` 375x812, `tablet` 768x1024, `desktop` 1280x720) or custom `width`/`height`. Returns screenshot.
`dom_inspect`	Get computed styles, classes, children, and bounding box for an element.
`get_page_info`	Returns the current URL, page title, viewport size, scroll position, and document dimensions.

Diffing

Tool	Description
`visual_diff`	Compare current page against a stored baseline. First call captures baseline, subsequent calls return a diff image with changed pixels highlighted and a percentage summary.
`multi_route_screenshot`	Screenshot multiple routes in one call. Returns labeled images for each route.

Debug

Tool	Description
`toggle_headless`	Switch between headless and visible browser. When visible, a Chrome window appears so you can watch the agent interact with your app in real time.

CLI Options

pagelens <url> [options]

Options:
  --no-headless        Show the browser window
  --viewport <preset>  Initial viewport: mobile | tablet | desktop (default: desktop)
  -h, --help           Show help

Architecture

src/
├── index.ts              # CLI entry point, arg parsing
├── server.ts             # MCP server, tool registration
├── browser.ts            # Puppeteer lifecycle, passive log/error collection
├── tools/
│   ├── screenshot.ts     # screenshot, screenshot_element, multi_route_screenshot
│   ├── console.ts        # console_logs, network_errors
│   ├── interact.ts       # click, type, navigate, set_viewport
│   ├── inspect.ts        # dom_inspect
│   └── diff.ts           # visual_diff
└── utils/
    └── viewport-presets.ts

Key design decisions:

Lazy connection — The MCP server starts immediately. Navigation to your app happens on the first tool call, so PageLens never crashes if your dev server isn't running yet.
Passive collection — Console logs and network errors are captured in ring buffers from the moment the browser launches. The agent checks when it wants to, not when events happen.
Screenshots after every interaction — click, type, navigate, and set_viewport all return a screenshot so the agent always sees the result of what it did.
Baseline storage — Visual diff baselines are stored in memory per route. No filesystem setup needed.

Development

git clone https://github.com/amoghmanral/pagelens.git
cd pagelens
npm install
npm run build

To test locally with Claude Code:

claude mcp add pagelens -- node /path/to/PageLens/dist/index.js http://localhost:3000

Tech Stack

TypeScript — Type-safe tool handlers and MCP integration
Puppeteer — Headless Chrome automation (bundles Chromium)
@modelcontextprotocol/sdk — Official MCP server SDK
pixelmatch + pngjs — Pixel-level image comparison for visual diffing

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

render-mcp A
io.github.RodRomer
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Browser Automation Testing & QA Tools
61
mcp A
io.github.pictify-io
Generate images, GIFs, and PDFs from HTML, URLs, or templates — from your AI agent.
Image & Video Processing Multimedia Processing
262
aiqaramba
io.github.ajrogier
Browser-based QA for AI-built software. Test pages with real browsers via agents.
Testing & QA Tools Browser Automation Agent Orchestration
2
Snapshot SiteOAuth
com.snapshot-site
Capture screenshots, detect visual regressions between page versions, and analyze with AI.
Testing & QA Tools Image & Video Processing AI & Machine Learning
41

Related MCP Servers

Browser-Debugger
Testing & QA Tools Browser Automation
Selvadinesh-giga
F
license
Not graded
quality
D
maintenance
Enables AI agents to automate and debug real Chromium browsers with capabilities like screenshots, video recording, performance analysis, visual regression testing, and OCR text extraction.
Updated 8 months ago (2026-01-30 08:16 UTC)
13
-
websight
Browser Automation Testing & QA Tools
h34tsink
A
license
Not graded
quality
D
maintenance
Enables AI agents to see, analyze, and visually verify web page changes through pixel-perfect diffing, theme extraction, layout analysis, and interactive element detection.
Updated 6 months ago (2026-03-07 17:47 UTC)
1 npm
MIT
AI Web Tester
Browser Automation Testing & QA Tools Developer Tools
SiamAlSobari
A
license
Not graded
quality
B
maintenance
Enables AI coding agents to autonomously interact with and test web applications in a real browser, providing DOM/Accessibility tree extraction, runtime telemetry, screenshot capture, and Markdown test reports.
Updated 16 days ago (2026-08-30 14:03 UTC)
32 npm
1
MIT
visual-browser-agent
Browser Automation Agent Orchestration Testing & QA Tools
Akakaui
A
license
Not graded
quality
B
maintenance
Enables AI coding agents to see and interact with real Chrome pages through structured DOM inspection, targeted screenshots, recordings, and human-in-the-loop approvals across major coding-agent hosts.
Updated 21 days ago (2026-08-25 16:50 UTC)
MIT