Content
# Claude Code Browser Automation
> Let Claude Code control your real browser - navigate, click, type, fill out forms, take screenshots, extract content - all driven by natural language.
[](LICENSE)
[](https://github.com/OUENMING/claude-code-browser)
[](README_en.md)
## Project Introduction
Claude Code Browser Automation System = Chrome/Edge Extension + MCP Server. **Real browser fingerprint + CDP synthetic input**, most headless browser solutions on the market fail when encountering strong anti-crawling sites like Xiaohongshu, Bilibili, and Zhihu, but this solution does not.
### Core Advantages
- **Real browser fingerprint**: No headless browser features exposed, CDP v1.3 native debugging protocol controls the page
- **Anti-anti-crawling**: Normal access to strong anti-crawling sites like Xiaohongshu, Zhihu, and Bilibili, no additional configuration required
- **Controlled component compatibility**: React/Vue form filling through prototype setter injection, not simple dispatchEvent
- **Content extraction dual engine**: Markdown structure + textContent full volume, choose or combine according to the scene
### Applicable Scenarios
- Social media content collection (Xiaohongshu/Zhihu/Bilibili posts, comment sections)
- Automatic form filling (including React/Vue controlled components)
- Page screenshots and quality detection
- Web end-to-end testing assistance
- Dynamic SPA content capture
## Function List
| Function Name | Function Description | Technical Stack | Update Time | Version |
|---------|---------|--------|----------|------|
| Navigation | Page jump, forward and backward | CDP Page | 2026-07-19 | v1.0.0 |
| Page Reading | Accessible element tree, keyword search, element waiting | Accessibility Tree | 2026-07-19 | v1.0.0 |
| Mouse and Keyboard Interaction | Click, input, scroll, drag, hover | CDP Input | 2026-07-19 | v1.0.0 |
| Form Filling | Controlled component compatible batch form filling | prototype setter | 2026-07-19 | v1.0.0 |
| Content Extraction | Markdown structure and pure text mode | content script | 2026-07-19 | v1.0.0 |
| Screenshot | Element screenshot, area screenshot, automatic quality reduction | CDP Screenshot | 2026-07-19 | v1.0.0 |
| JS Execution | Execute JavaScript in the page | CDP Runtime | 2026-07-19 | v1.0.0 |
| Debugging | Console log and network request reading | CDP Console/Network | 2026-07-19 | v1.0.0 |
| Tab Management | Tab list, new tab | chrome.tabs | 2026-07-19 | v1.0.0 |
| Dialog Handling | alert/confirm/prompt/beforeunload handling | CDP Page | 2026-07-19 | v1.0.0 |
## Technical Stack
| Technology | Version | Purpose | Official Website |
|------|------|------|------|
| Manifest V3 | — | Extension declaration | https://developer.chrome.com/docs/extensions/ |
| CDP v1.3 | — | Chrome DevTools Protocol debugging | https://chromedevtools.github.io/devtools-protocol/ |
| Node.js | >=18 | MCP Server running environment | https://nodejs.org |
| WebSocket | — | Extension ↔ MCP communication | — |
| WeakRef | — | Element ref mapping (no memory leak) | — |
### Technical Architecture
```
Claude Code ←──stdio──→ MCP Server (index.js) ←──ws:127.0.0.1:19222──→ Edge/Chrome Extension
│
CDP (DevTools Protocol)
│
Real browser tab
```
Startup process:
1. Edge/Chrome loads Extension (developer mode)
2. Claude Code automatically starts MCP Server
3. Extension connects to MCP Server via WebSocket
4. 14 browser tools automatically register
## Project Structure
```
claude-code-browser/
├── extension/ # Chrome/Edge Extension
│ ├── manifest.json # MV3 list
│ ├── background.js # Service Worker
│ ├── popup.html / popup.js # Connection status management UI
│ ├── content-scripts/
│ │ ├── accessibility-tree.js # Element mapping system (WeakRef bidirectional mapping)
│ │ ├── page-bridge.js # Form filling, text extraction, element search
│ │ ├── auto-capture.js # HTML → Markdown conversion
│ │ └── visual-indicator.js # Shadow DOM overlay UI
│ └── icons/ # Extension icons
├── mcp-server/
│ └── index.js # MCP Server (dual-mode WebSocket)
├── docs/ # Documentation site
│ ├── index.html
│ ├── technical-whitepaper.html
│ ├── project-story.html
│ ├── promo-browser.html
│ ├── promo-wechat.html
├── README_en.md # English README
└── LICENSE # MIT
```
## Installation Instructions
### Environment Requirements
- Node.js >= 18
- Edge or Chrome browser
- macOS / Linux / Windows supported
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI installed and authenticated
### Installation Steps
```bash
# Method 1: Register MCP Server
claude mcp add -s user browser -- node /path/to/claude-code-browser/mcp-server/index.js
```
### Load Extension
1. Open `edge://extensions` or `chrome://extensions`
2. Enable "Developer mode"
3. "Load unpacked extension" → Select `extension/` directory
4. Confirm Service Worker has no errors
## Usage Instructions
### 14 Tools Overview
#### Navigation
| Tool | Parameters | Description |
|------|------|------|
| `navigate` | `url`, `tabId?` | Navigate to URL, supports `"back"` / `"forward"` forward and backward |
#### Page Reading
| Tool | Parameters | Description |
|------|------|------|
| `read_page` | `filter?`, `depth?`, `max_chars?`, `tabId?` | Accessible element tree, with `[ref_N]` identifier. `filter="interactive"` only interactive elements (save token), `"all"` all |
| `find` | `query`, `max_results?`, `tabId?` | Search elements by keyword, multi-word scoring and sorting, return ref list |
| `wait_for` | `selector?`, `text?`, `timeout?`, `tabId?` | Wait for element or text to appear. Default 10s timeout, 300ms polling |
#### Interaction
| Tool | Parameters | Description |
|------|------|------|
| `computer` | `action` + 12 optional parameters | Mouse/keyboard/screenshot/scroll. Actions: `left_click`, `right_click`, `double_click`, `type`, `screenshot`, `scroll`, `key`, `hover` etc. Chinese use `Input.insertText` + random 10-30ms |
| `form_input` | `ref`+`value` or `fields[]`, `tabId?` | Set form field value (single or batch). React/Vue controlled component compatible. checkbox accepts boolean |
#### Content Extraction
| Tool | Parameters | Description |
|------|------|------|
| `get_page_text` | `max_chars?`, `tabId?` | Pure text extraction (textContent), automatically detect content container (10+ heuristic selectors). Suitable for social media/SPA |
| `get_page_markdown` | `max_chars?`, `tabId?` | Structured Markdown - title, link, code block, table, image, list, quote, folded block |
#### JS & Debugging
| Tool | Parameters | Description |
|------|------|------|
| `javascript_tool` | `text`, `tabId?` | Execute JS in the page. 100,000 character limit, scripting.executeScript fallback with CDP |
| `read_console_messages` | `tabId`, `onlyErrors?`, `pattern?`, `limit?` | Read console messages. Supports regular expression matching |
| `read_network_requests` | `tabId`, `urlPattern?`, `limit?` | Read HTTP network requests and status codes |
#### Tab Management
| Tool | Parameters | Description |
|------|------|------|
| `tabs_context` | — | List all tabs (ID/title/URL/active status). With connection health prefix |
| `tabs_create` | — | Create a new blank tab, title automatically adds `[AI]` prefix |
#### Dialog Handling
| Tool | Parameters | Description |
|------|------|------|
| `dismiss_dialog` | `action`, `promptText?`, `tabId?` | Close browser native dialog (alert/confirm/prompt/beforeunload) |
### Content Extraction Selection Guide
| Scenario | Recommended Tool | Reason |
|------|---------|------|
| Blog posts, technical documents | `get_page_markdown` preferred | Preserve structure (title/code/table) |
| Social media (Xiaohongshu/Zhihu/Bilibili) | `get_page_text` preferred | textContent no content leakage |
| Product page | `get_page_markdown` best | Structural information important |
| Complex SPA | `get_page_text` preferred | JS heavy applications may destroy tree structure |
| Unfamiliar page | Try both | Markdown see structure → pure text supplement leak |
### Typical Workflow
#### Xiaohongshu Search + Post Reading
```
1. navigate({ url: "xiaohongshu.com" })
2. read_page({ filter: "interactive" }) → Find search box [ref_N]
3. computer({ action: "left_click", ref: "ref_N" })
4. computer({ action: "type", text: "keywords\n" })
5. read_page({ filter: "interactive" }) → See search results
6. computer({ action: "left_click", ref: "ref_M" }) → Click post
7. get_page_text({ max_chars: 5000 }) → Read full text
```
#### Form Filling (React/Vue compatible)
```
1. navigate({ url: "example.com/form" })
2. read_page({ filter: "interactive" })
3. form_input({ fields: [{ref:"ref_N", value:"John"}, {ref:"ref_M", value:"test@test.com"}] })
4. computer({ action: "left_click", ref: "ref_submit" })
```
#### Dialog Handling
```
1. read_page and see:
⚠️ Browser dialog active: confirm("Confirm deletion?")
2. dismiss_dialog({ action: "accept" }) → Confirm
3. dismiss_dialog({ action: "dismiss" }) → Cancel
```
## Development Guide
### Local Development
No additional build steps, just modify files under `extension/` or `mcp-server/`.
```bash
# MCP Server development
cd mcp-server
node index.js
```
### Extension Component Description
| Component | Path | Description |
|------|------|------|
| Service Worker | `extension/background.js` | Dual-track keep-alive, WebSocket management, FIFO command queue, CDP management |
| Content Script | `extension/content-scripts/` | 4 independent scripts: element mapping / form filling / Markdown conversion / overlay UI |
| Popup | `extension/popup.html/js` | Connection status, port configuration, tab disconnection |
| MCP Server | `mcp-server/index.js` | Dual-mode WebSocket (server/client), multi-client routing |
### Contribution Guide
Welcome to submit issues and PRs. Changes covering both Extension and MCP Server sides ensure compatibility.
## FAQ
<details>
<summary>Extension cannot connect to MCP Server?</summary>
1. Confirm MCP Server registered: `claude mcp add` command correct
2. Check Extension's WebSocket port setting (popup page configurable, default 19222)
3. View Service Worker for errors
</details>
<details>
<summary>Some websites have no response?</summary>
Check if the page is a restricted URL (`chrome://`, `edge://`, `about:`, `devtools://`), these pages are blocked by the system. Common website interaction issues can be solved by refreshing the page or restarting the Extension.
</details>
<details>
<summary>What if it doesn't work after closing the lid?</summary>
This is a Chrome browser limitation - when the battery is in sleep mode, Chrome suspends the CDP connection. Make sure you don't need to use browser automation before closing the lid, or reload the Extension.
</details>
## Security Design
| Mechanism | Description |
|------|------|
| Local WebSocket | Only `127.0.0.1:19222`, not exposed to the network |
| Restricted URL interception | Block `chrome://`, `edge://`, `about:`, `devtools://` |
| CDP exclusive | Only Extension operates CDP, no direct DevTools exposure |
| PID file protection | `/tmp/claude-browser-mcp.pid`, automatic cleanup of expired processes |
| Tab isolation | Each tab independent CDP session; popup provides "disconnect" button |
## Roadmap
### Planned Features
- [ ] Multi-tab concurrent operation
- [ ] Record and playback functionality
- [ ] Chrome Web Store launch
- [ ] More CDP domain support
### Optimization Plan
- [ ] FIFO queue改为并发队列
- [ ] Screenshot quality reduction algorithm optimization (binary search instead of linear reduction)
- [ ] End-to-end health check mechanism
## License
[MIT](LICENSE)
Copyright (c) 2026 Owen
## Star History
<a href="https://www.star-history.com/?repos=OUENMING%2Fclaude-code-browser&type=date&legend=top-left">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=OUENMING/claude-code-browser&type=date&theme=dark&legend=top-left&sealed_token=1XVxC84Hpu0RJwfCDSX51MDZeW15ak8AkCigZFs43zLKRoT88M-4C3r8f79S3d5qfL3dTQIk6KQ2rwtfMy0QyC1dqnjvqkK6ujtmhY6uSk_Lo1WviIA6Gg" />
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=OUENMING/claude-code-browser&type=date&legend=top-left&sealed_token=1XVxC84Hpu0RJwfCDSX51MDZeW15ak8AkCigZFs43zLKRoT88M-4C3r8f79S3d5qfL3dTQIk6KQ2rwtfMy0QyC1dqnjvqkK6ujtmhY6uSk_Lo1WviIA6Gg" />
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=OUENMING/claude-code-browser&type=date&legend=top-left&sealed_token=1XVxC84Hpu0RJwfCDSX51MDZeW15ak8AkCigZFs43zLKRoT88M-4C3r8f79S3d5qfL3dTQIk6KQ2rwtfMy0QyC1dqnjvqkK6ujtmhY6uSk_Lo1WviIA6Gg" />
</picture>
</a>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available