DevTools Lens MCP

Give your AI agent Chrome DevTools.

DevTools Lens MCP is a production-oriented Model Context Protocol server that lets Claude, Codex, and other MCP clients inspect and control a live Chromium browser. It is built for frontend debugging—not just browser automation.

Ask an agent why a login request failed, which exception broke a click handler, what changed in the DOM after submit, or whether the current page has accessibility problems. The server combines Playwright's reliable lifecycle and interaction layer with direct Chrome DevTools Protocol diagnostics.

<!-- Demo GIF placeholder: console + failed network root-cause workflow -->

Why this exists

Browser automation tools can click and type, but debugging needs evidence: buffered console history, request/response details, stack traces, DOM state, computed styles, accessibility metadata, and before/after changes. DevTools Lens MCP exposes that evidence as focused, schema-validated tools that an AI agent can reason over.

Highlights

• 19 purpose-built debugging tools over MCP stdio
• Multiple isolated browser sessions with optional single-session shorthand
• CDP-native console, exception, and network event collection
• Grouped console errors with likely categories
• Failed-request detection for HTTP, DNS, timeout, refused, CORS, and aborted requests
• Bounded textual response-body inspection and default credential redaction
• Compact DOM snapshots, element styles/layout, and structural DOM diffing
• Click impact capture: DOM, console, network, and URL before/after evidence
• Page and element screenshots written to a controlled output directory
• axe-core accessibility analysis
• Strict TypeScript, Zod inputs, Vitest coverage, Docker, and CI

Architecture

flowchart LR
  Client[Claude / Codex / MCP client] -->|MCP stdio| Server[MCP tool registry]
  Server --> Schemas[Zod validation + structured errors]
  Server --> Manager[BrowserManager]
  Manager --> S1[BrowserSession A]
  Manager --> S2[BrowserSession B]
  S1 --> PW[Playwright lifecycle + interactions]
  S1 --> CDP[Chrome DevTools Protocol]
  CDP --> Console[Console ring buffer]
  CDP --> Network[Network ring buffer]
  Server --> Services[DOM / console / network / a11y / screenshot services]
  Services --> S1

Each session owns one Chromium page, one CDP session, independent console/network buffers, active requests, and lifecycle timestamps. The transport is isolated in the server entry point so HTTP transports can be added later without rewriting browser services.

Five-minute setup

Requirements: Node.js 20.19+ and npm.

npm install -g devtools-lens-mcp
npx playwright install chromium
devtools-lens-mcp

For one-command client usage, configure the client to run:

npx -y devtools-lens-mcp

When developing from source:

git clone https://github.com/aakcay5656/devtools-lens-mcp.git
cd devtools-lens-mcp
npm install
npx playwright install chromium
npm run build
npm start

MCP client configuration

Claude Desktop

Add this server to the mcpServers object in Claude Desktop's configuration:

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

Restart Claude Desktop after saving the file.

Codex CLI or IDE extension

The CLI and IDE extension share MCP configuration. Add the server with:

codex mcp add devtools-lens -- npx -y devtools-lens-mcp

Or add it manually to ~/.codex/config.toml:

[mcp_servers.devtools-lens]
command = "npx"
args = ["-y", "devtools-lens-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120

Tools

Tool	Purpose
browser_launch	Launch Chromium with URL, viewport, and headless options
browser_connect	Connect to an existing CDP remote-debugging endpoint
browser_navigate	Navigate and wait for a lifecycle state
browser_get_page_info	Get URL, title, viewport, UA, loading state, and DOM/resource counts
browser_get_console_logs	Filter buffered console history
browser_get_console_errors	Group errors/exceptions and classify likely causes
browser_get_network_requests	Filter complete session request history
browser_get_failed_requests	Explain HTTP and transport failures
browser_get_request_details	Get headers, payload, initiator, timing, and bounded text body
browser_inspect_element	Get layout, visibility, styles, accessible identity, and selector
browser_get_dom_snapshot	Capture a compact, depth-limited DOM model
browser_click	Click and optionally capture diagnostic changes
browser_fill	Fill editable elements with password-safe results
browser_select	Select an option by value, label, or index
browser_press_key	Press keys or chords on a target or page
browser_screenshot	Save page or element screenshots
browser_get_accessibility_issues	Run axe-core and return actionable findings
browser_compare_dom	Compare snapshots by additions/removals/text/attributes/visibility
browser_close	Safely close a session

All browser-facing tools accept sessionId. It may be omitted when exactly one session exists. Ambiguous and invalid sessions return structured errors with available session IDs.

Example workflow

1. Ask the client to call browser_launch with { "headless": true, "url": "https://example.com" }.
2. Call browser_get_console_errors and browser_get_failed_requests to establish a baseline.
3. Call browser_click with { "selector": "button[type=submit]", "captureChanges": true }.
4. Inspect new requests with browser_get_request_details and the DOM diff from the click result.
5. Call browser_close when finished.

Prompts to try

• “Find all console errors on this page and explain their likely causes.”
• “Click the login button and analyze what fails.”
• “Inspect failed API requests and suggest a fix.”
• “Compare the page before and after submitting this form.”
• “Find accessibility issues in the current page.”
• “Inspect the styling and accessibility properties of the submit button.”

<!-- Demo GIF placeholder: captureChanges DOM/network/console comparison -->

Configuration

Environment variable	Default	Meaning
DEVTOOLS_LENS_OUTPUT_DIR	./output	Only directory used for screenshots
DEVTOOLS_LENS_MAX_CONSOLE	2000	Console buffer capacity per session
DEVTOOLS_LENS_MAX_NETWORK	2000	Network buffer capacity per session
DEVTOOLS_LENS_MAX_BODY_BYTES	1000000	Maximum returned response-body bytes

Security

Treat the browser and every page it opens as untrusted.

• authorization, cookie, set-cookie, x-api-key, and proxy-authorization headers are masked by default.
• Password inputs are never returned by fill results or DOM snapshot value attributes.
• Binary response bodies are not returned; textual bodies are byte-limited.
• Screenshots can only be written under the configured output directory.
• The server exposes no arbitrary shell command or general-purpose JavaScript evaluation tool.
• Localhost and private-network navigation are not blocked. This is intentional for local frontend debugging, but it makes SSRF-style access possible when an agent follows untrusted instructions. Run the server with only the network access it needs.
• Never attach this server to a trusted personal browser profile. Use a fresh, disposable debugging profile with no saved credentials, cookies, extensions, or open authenticated tabs.
• Response bodies and page text may themselves contain secrets. Review outputs before sharing them.
• Connecting by remote debugging endpoint grants powerful control over that browser. Bind debugging ports to loopback and do not expose them publicly.

For untrusted targets, prefer the Docker image with a restricted network policy and disposable filesystem. Report vulnerabilities privately according to SECURITY.md.

Development

npm run dev
npm run typecheck
npm run lint
npm run test:unit
npm run test:integration
npm run test
npm run build
npm run format

Integration tests start a local fixture and a real headless Chromium instance. Install the browser once with npx playwright install chromium.

Docker

docker build -t devtools-lens-mcp .
docker run --rm -i -v "$PWD/output:/app/output" devtools-lens-mcp

The image is designed for MCP stdio (-i is required). See docker-compose.yml for a minimal example.

Roadmap

• React component tree, props, and state inspection
• Redux and Zustand state inspection
• Vue component inspection
• Performance trace analysis and Lighthouse integration
• CSS and JavaScript coverage
• Source-map-aware source navigation
• Breakpoints, step debugging, and WebSocket inspection
• IndexedDB, localStorage, sessionStorage, and cookie editing
• Mobile device emulation and multi-tab support
• Browser recording and replay
• AI-driven automatic root-cause analysis

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md, keep tools narrowly focused on frontend diagnosis, add Zod validation for inputs, and include unit or Chromium integration coverage for behavior changes.

License

MIT © DevTools Lens MCP contributors.