Pagelens MCP

🚀 PageLens

A MCP server that provides AI coding agents with visual feedback on frontend apps. With just one command and no configuration required, your AI agent can now view your app, click buttons, read console errors, and detect visual changes.

🚀 Quick Start

1. Start your dev server

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

2. Add PageLens to your MCP config

⚠️ Important 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.

✨ Features

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.

📦 Installation

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

💻 Usage Examples

Basic Usage

npx pagelens http://localhost:3000

📚 Documentation

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:

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

PageLens eliminates this loop entirely.

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 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.

Tools

Observation

Interaction

Diffing

Debug

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.

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