browser-lens-mcp

Your browser's UI, deeply understood by your IDE's AI agent.

How It Works

Browser Lens connects your IDE's AI agent to any running web page. Ask about any UI element and get its exact styles, layout, screenshot, and fix suggestions — with zero code changes.

The flow:

1. Bookmarklet runs in your browser, captures DOM, CSS, layout, screenshots
2. WebSocket streams data in real-time + receives commands from server
3. MCP server stores and indexes everything, exposes 30 tools, 12 resources, 5 prompts
4. IDE AI agent queries tools via stdio — inspect any element, take screenshots on demand, compare with Figma

Key Capabilities

What Gets Captured

Quick Start

Step 1 — Configure your IDE

{
  "mcpServers": {
    "browser-lens": {
      "command": "npx",
      "args": ["-y", "browser-lens-mcp@latest"]
    }
  }
}

{
  "servers": {
    "browser-lens": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "browser-lens-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "browser-lens": {
      "command": "npx",
      "args": ["-y", "browser-lens-mcp@latest"],
      "env": {
        "MCP_BROWSER_LENS_PORT": "3300",
        "MCP_BROWSER_LENS_WS_PORT": "3301",
        "MCP_BROWSER_LENS_CDP_PORT": "9222"
      }
    }
  }
}

@browser-lens Chụp screenshot cho tôi xem
@browser-lens/css-colors Show me the color palette
/compare_with_figma

claude mcp add browser-lens npx -y browser-lens-mcp@latest

{
  "mcpServers": {
    "browser-lens": {
      "command": "npx",
      "args": ["-y", "browser-lens-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "browser-lens": {
      "type": "local",
      "command": ["npx", "-y", "browser-lens-mcp@latest"]
    }
  }
}

{
  "context_servers": {
    "browser-lens": {
      "command": { "path": "npx", "args": ["-y", "browser-lens-mcp@latest"] }
    }
  }
}

Custom ports (avoid conflicts):

{
  "mcpServers": {
    "browser-lens": {
      "command": "npx",
      "args": ["-y", "browser-lens-mcp@latest"],
      "env": {
        "MCP_BROWSER_LENS_PORT": "3300",
        "MCP_BROWSER_LENS_WS_PORT": "3301"
      }
    }
  }
}

Step 2 — Connect your browser

Option A: Chrome Extension (recommended — persists across page reloads)

# Find the extension folder
ls node_modules/browser-lens-mcp/extension/

1. Open chrome://extensions in Chrome/Edge
2. Enable Developer Mode (top right)
3. Click Load unpacked
4. Select node_modules/browser-lens-mcp/extension/
5. Done — auto-connects on every page load, survives reload!

Configure ports via the extension popup icon.

Option B: Bookmarklet (zero install, one-time per page)

1. Open http://localhost:3202 (or your custom port)
2. Drag the bookmarklet to your bookmarks bar
3. Navigate to any web app → click the bookmarklet

[BrowserLens] WebSocket connected to ws://localhost:3203
[BrowserLens] DOM captured: 250 elements
[BrowserLens] Elements captured: 30
[BrowserLens] CSS vars captured: 12
[BrowserLens] Screenshot OK: 1440x900
[BrowserLens] Sync complete

Step 3 — Ask your AI agent

@browser-lens What does the header look like? Show me a screenshot.
@browser-lens What are the 2 buttons in the header? What colors are they?
@browser-lens Compare the hero section with Figma: fontSize 48px, color #ffffff, fontWeight 800
@browser-lens This button looks wrong — find the source file and suggest a fix
@browser-lens Run a full visual QA on this page

Figma Design Comparison

Scoring:

Works with any design tool — Figma, Sketch, Adobe XD, Zeplin. Just provide CSS values.

MCP Tools (30)

Live Browser Commands (2 tools) ⚡

DOM Inspection (5 tools)

CSS Analysis (4 tools)

Layout & Spacing (3 tools)

Visual & Screenshots (4 tools)

Design Comparison (4 tools)

Page Analysis (4 tools)

General (4 tools)

MCP Prompts (5) — / Commands in IDE

Type / in your IDE chat to see these guided workflows:

Example usage in Antigravity/Cursor:

/compare_with_figma
→ AI reads current page data, asks for Figma specs, runs comparisons, suggests fixes

/audit_ui
→ AI analyzes colors (too many?), typography (consistent?), spacing (scale?), a11y (issues?)

MCP Resources (12) — @ References in IDE

Type @mcp:browser-lens/ in your IDE to access these data sources directly:

Example usage:

@browser-lens/css-colors Tell me the primary colors used on this page
@browser-lens/dom-snapshot Show me the semantic structure
@browser-lens/accessibility-info Are there any accessibility issues?

Resources vs Tools:

• Resources (@) = Read-only data snapshots. Fast, no browser command needed. Use for quick lookups.
• Tools = Actions that can query the browser live, take screenshots, compare with Figma. Use for interactive work.

Bidirectional Command System

Unlike other MCP tools that only read cached data, Browser Lens has a live command channel:

IDE → MCP Server → WebSocket → Browser Bookmarklet
                                     ↓
                              Execute command
                                     ↓
IDE ← MCP Server ← WebSocket ← Send result

Commands the server can send to the browser:

• screenshot — Capture viewport screenshot (cross-origin images auto-replaced with placeholders)
• element_screenshot — Capture a specific element by CSS selector
• query_element — Inspect any element by CSS selector on-demand
• fullsync — Trigger a full data re-capture

Screenshots (CDP — 100% Reliable)

Screenshots use Chrome DevTools Protocol (CDP) via puppeteer-core — captures exactly what you see in the browser. No CORS issues, no CSP restrictions, works on any page.

Setup: Launch browser with remote debugging

/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

google-chrome --remote-debugging-port=9222

/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge --remote-debugging-port=9222

# Add to ~/.zshrc or ~/.bashrc
alias brave-debug='/Applications/Brave\ Browser.app/Contents/MacOS/Brave\ Browser --remote-debugging-port=9222'
alias chrome-debug='/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222'

# Then just run
brave-debug

Verify CDP is running:

curl http://127.0.0.1:9222/json/version
# Should show: {"Browser":"Brave/...","webSocketDebuggerUrl":"ws://..."}

Screenshot tools

Screenshot fallback chain

trigger_screenshot / screenshot_element
  ├─ 1. CDP (puppeteer-core) ← primary, 100% reliable
  ├─ 2. WS command → bookmarklet → html2canvas (simple pages)
  └─ 3. Return cached screenshot if available

CDP auto-scans ports 9222, 9229, 9333. Set MCP_BROWSER_LENS_CDP_PORT for custom port.

Configuration

Full config example:

{
  "mcpServers": {
    "browser-lens": {
      "command": "npx",
      "args": ["-y", "browser-lens-mcp@latest"],
      "env": {
        "MCP_BROWSER_LENS_PORT": "3300",
        "MCP_BROWSER_LENS_WS_PORT": "3301",
        "MCP_BROWSER_LENS_CDP_PORT": "9222"
      }
    }
  }
}

---

## License

MIT — see [LICENSE](LICENSE)

---

<div align="center">
  <sub>Built by <a href="https://github.com/nano-step"><strong>nano-step</strong></a> — Copyright &copy; 2026 Hoai Nho Nguyen</sub>
</div>