# DevTools Lens MCP

> **Give your AI agent Chrome DevTools.**

[![npm](https://img.shields.io/npm/v/devtools-lens-mcp)](https://www.npmjs.com/package/devtools-lens-mcp)
[![CI](https://github.com/aakcay5656/devtools-lens-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aakcay5656/devtools-lens-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

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

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

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

```bash
npx -y devtools-lens-mcp
```

When developing from source:

```bash
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:

```json
{
  "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:

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

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

```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](SECURITY.md).

## Development

```bash
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

```bash
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](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](LICENSE) © DevTools Lens MCP contributors.