# Playwright React Debug MCP

[![npm version](https://img.shields.io/npm/v/playwright-react-debug-mcp.svg)](https://www.npmjs.com/package/playwright-react-debug-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)

**Debug React applications with AI assistance using Claude and Playwright.**

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that gives Claude the ability to interact with live web applications through a browser. Navigate pages, inspect the DOM, monitor network requests, debug React components, and analyze errors—all through natural conversation.

<!--
Add a demo GIF here:
![Demo](./docs/assets/demo.gif)
-->

---

## Why Use This?

| Traditional Debugging | With Playwright React Debug MCP |
|-----------------------|---------------------------|
| Manually reproduce issues | "Navigate to /dashboard and check for errors" |
| Screenshot and paste into chat | Claude sees the live page and interacts directly |
| Copy-paste console errors | Console logs captured automatically |
| Open React DevTools manually | Claude queries component tree with state/props |
| Check Network tab for failures | All HTTP traffic monitored and analyzed |

---

## Features

- **67 debugging tools** across 15 categories
- **Browser Control** - Navigate, click, fill forms, keyboard, drag & drop, automate user flows
- **Tabs, Dialogs & Files** - Multi-tab support, alert/confirm/prompt handling, uploads and downloads
- **DOM Inspection** - Element details, computed styles, text extraction, token-efficient ARIA snapshots
- **Network Monitoring** - Request/response bodies, headers, timing
- **Network Mocking** - Mock API responses to test loading/error states without a backend
- **Console Capture** - Errors, warnings, logs with filtering
- **React DevTools** - Component tree, props, state, hooks inspection
- **State Management** - Redux, Zustand, React Query, Context inspection
- **Cookies & Storage** - Inspect and modify cookies, localStorage, sessionStorage
- **Device Emulation** - Mobile devices, dark mode, geolocation, offline, CPU/network throttling
- **Performance** - Render tracking, slow components, Web Vitals
- **Error Detection** - Hydration errors, error boundaries, memory leaks
- **Accessibility** - WCAG-style audits, ARIA tree inspection
- **Error Analysis** - AI-powered analysis with suggested fixes
- **MCP tool annotations** - Read-only/destructive hints so clients can auto-approve safe inspection tools

---

## Quick Start

### Install

```bash
npm install -g playwright-react-debug-mcp
npx playwright install chromium
```

### Configure Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "playwright-debug": {
      "command": "npx",
      "args": ["playwright-react-debug-mcp"]
    }
  }
}
```

### Configure Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "playwright-debug": {
      "command": "npx",
      "args": ["playwright-react-debug-mcp"],
      "transport": "stdio"
    }
  }
}
```

### Try It

```
You: Navigate to https://example.com and take a screenshot

Claude: I'll navigate to the page and capture a screenshot.
[Browser opens, navigates, returns screenshot]

Done! The page shows...
```

---

## Example Session

```
You: Navigate to my app at localhost:3000/login and try logging in
     with test@example.com

Claude: I'll navigate to the login page and fill in the credentials.

[Navigates, fills email/password, clicks submit]

The login failed. Let me check what happened:

- Console: "TypeError: Cannot read property 'token' of undefined"
- Network: POST /api/auth returned 200 but body is empty
- React: AuthProvider shows { isAuthenticated: false, error: null }

The API returns 200 without a token. The frontend expects response.data.token
but data is undefined. The error state isn't being set because the HTTP
status was 200.

Suggestions:
1. Backend should return { data: { token: "..." } } or proper error status
2. Frontend should validate response structure, not just HTTP status
```

---

## Available Tools

### Navigation & Interaction (14 tools)
| Tool | Description |
|------|-------------|
| `navigate` | Navigate to URL with wait conditions |
| `click` | Click elements (left/right/double) |
| `fill` | Fill form fields |
| `select` | Select dropdown options |
| `type` | Type text character-by-character |
| `press_key` | Press keyboard keys (Enter, Escape, Control+A...) |
| `hover` | Hover over elements |
| `drag` | Drag and drop between elements |
| `scroll` | Scroll page or element into view |
| `wait_for` | Wait for element/navigation |
| `upload_file` | Set files on a file input |
| `go_back` | Browser back |
| `go_forward` | Browser forward |
| `reload` | Reload page |

### Tabs, Dialogs & Downloads (7 tools)
| Tool | Description |
|------|-------------|
| `list_tabs` | List open tabs |
| `new_tab` | Open a new tab |
| `switch_tab` | Switch the active tab |
| `close_tab` | Close a tab |
| `set_dialog_action` | Auto-accept or dismiss alert/confirm/prompt |
| `get_dialogs` | Log of dialogs and how they were handled |
| `list_downloads` | Downloads captured this session |

### Inspection (4 tools)
| Tool | Description |
|------|-------------|
| `snapshot` | Token-efficient ARIA snapshot (best first look at a page) |
| `get_dom` | Summarized DOM tree |
| `get_element` | Element details with styles |
| `get_text_content` | Extract visible text |

### Network (6 tools)
| Tool | Description |
|------|-------------|
| `get_network` | View requests with filtering |
| `get_request_detail` | Full request/response details |
| `clear_network` | Clear captured requests |
| `mock_route` | Mock API responses by URL pattern (status, body, delay) |
| `unmock_route` | Remove a mock |
| `list_mocks` | Active mocks and hit counts |

### Console (2 tools)
| Tool | Description |
|------|-------------|
| `get_console` | View logs with filtering |
| `clear_console` | Clear captured logs |

### React (4 tools)
| Tool | Description |
|------|-------------|
| `get_react_tree` | Component tree with hooks |
| `find_component` | Search components by name |
| `get_component_state` | Detailed state/props |
| `collect_component_instances` | All instances of a component |

### State Management (4 tools)
| Tool | Description |
|------|-------------|
| `get_redux_state` | Redux store state + actions |
| `get_zustand_stores` | Zustand store inspection |
| `get_react_query_cache` | React Query cache |
| `get_context_values` | React Context values |

### Cookies & Storage (6 tools)
| Tool | Description |
|------|-------------|
| `get_cookies` | Browser cookies |
| `set_cookie` | Set a cookie (e.g. inject a session token) |
| `clear_cookies` | Clear all cookies |
| `get_storage` | localStorage / sessionStorage contents |
| `set_storage_item` | Set a storage item |
| `clear_storage` | Clear web storage |

### Device & Environment Emulation (7 tools)
| Tool | Description |
|------|-------------|
| `set_viewport` | Resize the viewport |
| `emulate_device` | Emulate a device ("iPhone 15", "Pixel 7"...) |
| `emulate_media` | Dark mode, reduced motion, print media |
| `set_geolocation` | Set browser geolocation |
| `set_offline` | Toggle offline mode |
| `throttle_network` | Slow-3G/fast-3G/4G network throttling |
| `throttle_cpu` | CPU slowdown for performance testing |

### Performance (3 tools)
| Tool | Description |
|------|-------------|
| `get_render_count` | Component render tracking |
| `get_slow_components` | Slow component detection |
| `get_web_vitals` | Core Web Vitals (LCP, CLS, etc.) |

### Error Detection (3 tools)
| Tool | Description |
|------|-------------|
| `find_hydration_errors` | SSR hydration mismatches |
| `get_error_boundaries` | React error boundaries |
| `detect_memory_leaks` | Memory leak indicators |

### Accessibility (2 tools)
| Tool | Description |
|------|-------------|
| `audit_accessibility` | WCAG-style audit |
| `get_aria_tree` | Accessibility tree |

### Advanced (5 tools)
| Tool | Description |
|------|-------------|
| `screenshot` | Capture page or element |
| `save_pdf` | Save page as PDF (headless mode) |
| `evaluate_js` | Execute JavaScript |
| `explain_error` | AI error analysis |
| `get_debug_summary` | Page state overview |

---

## Use Cases

**Interactive Debugging**
```
What errors are on this page?
Why did the form submission fail?
```

**Automated Testing**
```
Fill the registration form and verify it submits successfully
Click through the checkout flow and check for errors
```

**React Development**
```
Find the UserProfile component and show its state
What props are being passed to the Modal?
Collect all Button instances and compare their usage
```

**API Integration**
```
What requests were made when I clicked submit?
Show me the response from the failed API call
```

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MAX_CONSOLE_ENTRIES` | 200 | Console log buffer size |
| `MAX_NETWORK_ENTRIES` | 100 | Network request buffer size |
| `BROWSER_HEADLESS` | false | Run browser headless (required for `save_pdf`) |

```json
{
  "mcpServers": {
    "playwright-debug": {
      "command": "npx",
      "args": ["playwright-react-debug-mcp"],
      "env": {
        "BROWSER_HEADLESS": "true"
      }
    }
  }
}
```

---

## Development

```bash
# Clone
git clone https://github.com/Lars-Albinsson/playwright-react-debug-mcp
cd playwright-react-debug-mcp

# Install
npm install
npx playwright install chromium

# Build
npm run build

# Run
npm start

# Watch mode
npm run dev
```

---

## Documentation

- [Getting Started](https://lars-albinsson.github.io/playwright-react-debug-mcp/getting-started)
- [Tools Reference](https://lars-albinsson.github.io/playwright-react-debug-mcp/tools/)
- [Examples](https://lars-albinsson.github.io/playwright-react-debug-mcp/examples/)

---

## Requirements

- Node.js 18+
- Playwright (Chromium)
- Claude Desktop or Claude Code

---

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

## How It Compares

| | This project | [playwright-mcp](https://github.com/microsoft/playwright-mcp) | [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) |
|---|---|---|---|
| Browser automation | ✅ | ✅ | ✅ |
| Console & network capture | ✅ | ✅ | ✅ |
| Network mocking | ✅ | ✅ | ❌ |
| Device emulation & throttling | ✅ | partial | ✅ |
| **React component tree, props, state, hooks** | ✅ | ❌ | ❌ |
| **Redux / Zustand / React Query / Context inspection** | ✅ | ❌ | ❌ |
| **Hydration errors, error boundaries, render tracking** | ✅ | ❌ | ❌ |

If you need generic browser automation at scale, Microsoft's playwright-mcp is excellent. This project's focus is being a **one-stop shop for React debugging**: everything above plus React internals no other MCP server inspects.

## Acknowledgements

Tool design in the tabs, dialogs, mocking, and emulation categories was inspired by the excellent [microsoft/playwright-mcp](https://github.com/microsoft/playwright-mcp) and [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) projects (implementations are original to this codebase).

## Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Playwright](https://playwright.dev/)
- [Claude](https://claude.ai/)