@natchs/browser-mcp 2.6.5 → 2.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +367 -367
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,367 +1,367 @@
|
|
|
1
|
-
# @natchs/browser-mcp
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@natchs/browser-mcp)
|
|
4
|
-
[](LICENSE)
|
|
5
|
-
[](package.json)
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
# Your AI Agent's Browser Superpowers — Reverse Engineering, Network Interception & Full Browser Control
|
|
10
|
-
|
|
11
|
-
**`@natchs/browser-mcp`** is a Model Context Protocol server that gives AI agents **complete browser control** — navigate, click, scrape, intercept network traffic, export HAR files, capture WebSocket frames, deobfuscate JavaScript, and more. All through a single MCP interface.
|
|
12
|
-
|
|
13
|
-
Three browser modes (fresh / persistent / connect), production-grade security, 50+ tools, 9 categories. Built for reverse engineers, data extraction pipelines, and AI-powered automation.
|
|
14
|
-
|
|
15
|
-
---
|
|
16
|
-
|
|
17
|
-
## Features
|
|
18
|
-
|
|
19
|
-
- 🔍 **Reverse Engineering Toolkit** — JS beautify/deobfuscate, API endpoint discovery, auth flow analysis
|
|
20
|
-
- 🌐 **Web Scraping** — HTML, Markdown, text, CSS selectors, tables, Schema.org JSON-LD, Open Graph
|
|
21
|
-
- 📡 **Network Intelligence** — Real-time HTTP/HTTPS interception, WebSocket frame capture, HAR/JSON/CSV export
|
|
22
|
-
- 🕶️ **Stealth Mode** — Fingerprint rotation, human behavior simulation
|
|
23
|
-
- 🔐 **Enterprise Security** — SSRF protection, DNS rebind prevention, path traversal guards, cookie leak prevention
|
|
24
|
-
- 🧩 **3 Browser Profiles** — Fresh (isolated), Persistent (your Chrome profile, auto-detected), Connect (existing browser)
|
|
25
|
-
- 📦 **50+ Tools** — Navigation, interaction, extraction, network, browser control, sessions, admin, RE, stealth
|
|
26
|
-
- ⚡ **Production Ready** — Rate limiting, LRU cache, structured logging, metrics, plugin system, configurable timeouts
|
|
27
|
-
|
|
28
|
-
---
|
|
29
|
-
|
|
30
|
-
## Quick Start
|
|
31
|
-
|
|
32
|
-
```bash
|
|
33
|
-
# Install
|
|
34
|
-
npm install @natchs/browser-mcp
|
|
35
|
-
|
|
36
|
-
# Run (Chromium installs automatically ~30s on first run)
|
|
37
|
-
npx @natchs/browser-mcp
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
### MCP Client Config
|
|
41
|
-
|
|
42
|
-
Add to Claude Desktop, Cursor, VS Code (Cline, Roo Code), Continue.dev, or any MCP-compatible client:
|
|
43
|
-
|
|
44
|
-
```json
|
|
45
|
-
{
|
|
46
|
-
"mcpServers": {
|
|
47
|
-
"browser-mcp": {
|
|
48
|
-
"command": "npx",
|
|
49
|
-
"args": ["@natchs/browser-mcp"]
|
|
50
|
-
}
|
|
51
|
-
}
|
|
52
|
-
}
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
### Local Build
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
git clone https://github.com/natchs/browser-mcp.git
|
|
59
|
-
cd browser-mcp
|
|
60
|
-
npm ci
|
|
61
|
-
npm run build
|
|
62
|
-
npx @natchs/browser-mcp
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
---
|
|
66
|
-
|
|
67
|
-
## Browser Modes
|
|
68
|
-
|
|
69
|
-
The `BROWSER_MODE` environment variable controls which browser profile the agent uses:
|
|
70
|
-
|
|
71
|
-
| Mode | Description | Best For |
|
|
72
|
-
|------|-------------|----------|
|
|
73
|
-
| `fresh` (default) | Playwright's own Chromium. Fresh profile every time — no cookies, history, or extensions carried over | Clean room analysis, leave-no-trace operations |
|
|
74
|
-
| `persistent` | **Your real Chrome profile.** Auto-detected since v2.3.0. All cookies, sessions, extensions, and logged-in accounts available to the agent | When the agent needs to act "as you" — Gmail, GitHub, ChatGPT, corporate portals |
|
|
75
|
-
| `connect` | Attaches to your already-running Chrome via CDP debug port | Hybrid workflows — manually drive Chrome while the agent assists |
|
|
76
|
-
|
|
77
|
-
### Persistent (auto-detect)
|
|
78
|
-
|
|
79
|
-
```bash
|
|
80
|
-
BROWSER_MODE=persistent npx @natchs/browser-mcp
|
|
81
|
-
```
|
|
82
|
-
|
|
83
|
-
Since v2.3.0 the Chrome profile is auto-detected on Windows/macOS/Linux. No path needed. To specify a manual path:
|
|
84
|
-
|
|
85
|
-
```bash
|
|
86
|
-
BROWSER_MODE=persistent BROWSER_USER_DATA_DIR=C:\Users\...\User Data\Default npx @natchs/browser-mcp
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
### Connect (attach to existing Chrome)
|
|
90
|
-
|
|
91
|
-
```bash
|
|
92
|
-
# Start Chrome with debug port first:
|
|
93
|
-
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
|
|
94
|
-
|
|
95
|
-
# Then launch the agent:
|
|
96
|
-
BROWSER_MODE=connect npx @natchs/browser-mcp
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
### Per-Mode Client Profiles
|
|
100
|
-
|
|
101
|
-
```json
|
|
102
|
-
{
|
|
103
|
-
"mcpServers": {
|
|
104
|
-
"browser-mcp-persistent": {
|
|
105
|
-
"command": "npx",
|
|
106
|
-
"args": ["@natchs/browser-mcp"],
|
|
107
|
-
"env": { "BROWSER_MODE": "persistent" }
|
|
108
|
-
},
|
|
109
|
-
"browser-mcp-fresh": {
|
|
110
|
-
"command": "npx",
|
|
111
|
-
"args": ["@natchs/browser-mcp"],
|
|
112
|
-
"env": { "BROWSER_MODE": "fresh" }
|
|
113
|
-
}
|
|
114
|
-
}
|
|
115
|
-
}
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
---
|
|
119
|
-
|
|
120
|
-
## Environment Variables
|
|
121
|
-
|
|
122
|
-
All configuration is managed through environment variables.
|
|
123
|
-
|
|
124
|
-
### Browser
|
|
125
|
-
|
|
126
|
-
| Variable | Default | Description | Required |
|
|
127
|
-
|----------|---------|-------------|----------|
|
|
128
|
-
| `BROWSER_MODE` | `fresh` | Browser mode: `fresh`, `persistent`, `connect` | No |
|
|
129
|
-
| `BROWSER_HEADLESS` | `true` | Run in headless mode (`true`/`false`/`1`/`0`/`yes`/`no`) | No |
|
|
130
|
-
| `BROWSER_USER_DATA_DIR` | — | Chrome user data directory (absolute path) | No |
|
|
131
|
-
| `BROWSER_CHANNEL` | `""` | Browser channel (`chrome`, `msedge`, `chromium`, etc.) | No |
|
|
132
|
-
| `BROWSER_DEBUG_PORT` | `9222` | CDP debug port number | No |
|
|
133
|
-
| `BROWSER_AUTO_DETECT_PROFILE` | `true` | Auto-detect Chrome profile location | No |
|
|
134
|
-
| `BROWSER_VIEWPORT_WIDTH` | `1280` | Viewport width (px) | No |
|
|
135
|
-
| `BROWSER_VIEWPORT_HEIGHT` | `720` | Viewport height (px) | No |
|
|
136
|
-
| `BROWSER_USER_AGENT` | — | Custom User-Agent string | No |
|
|
137
|
-
| `BROWSER_LOCALE` | — | Browser locale (e.g. `en-US`) | No |
|
|
138
|
-
| `BROWSER_TIMEOUT` | `30000` | Browser operation timeout (ms) | No |
|
|
139
|
-
| `BROWSER_AUTO_INSTALL` | `true` | Auto-install Chromium (`false` to disable) | No |
|
|
140
|
-
|
|
141
|
-
### Network & Download
|
|
142
|
-
|
|
143
|
-
| Variable | Default | Description | Required |
|
|
144
|
-
|----------|---------|-------------|----------|
|
|
145
|
-
| `NETWORK_HAR_ENABLED` | `1` | Enable HAR capture (`0` to disable) | No |
|
|
146
|
-
| `NETWORK_MAX_ENTRIES` | `5000` | Max network entries stored | No |
|
|
147
|
-
| `NETWORK_MAX_RESPONSE_BODY_SIZE` | `262144` | Max response body size (bytes) | No |
|
|
148
|
-
| `NETWORK_STORE_RESPONSE_BODIES` | `false` | Keep response bodies in memory | No |
|
|
149
|
-
| `NETWORK_EXCLUDE_BODY_TYPES` | `["image","media","font","stylesheet"]` | Body types excluded from storage (JSON array) | No |
|
|
150
|
-
| `NETWORK_EXPORT_DIR` | `./network-logs` | Network log export directory | No |
|
|
151
|
-
| `NETWORK_CAPTURE_FAILED` | `true` | Capture failed requests too | No |
|
|
152
|
-
| `NETWORK_CAPTURE_WS` | `true` | Capture WebSocket frames | No |
|
|
153
|
-
| `NETWORK_WS_MAX_FRAMES` | `1000` | Max WebSocket frames stored | No |
|
|
154
|
-
| `NETWORK_WS_MAX_FRAME_SIZE` | `65536` | Max WebSocket frame payload (bytes) | No |
|
|
155
|
-
| `NETWORK_MAX_MEMORY_MB` | `256` | Max memory for network capture (MB) | No |
|
|
156
|
-
| `NETWORK_CAPTURE_REQUEST_BODY` | `false` | Capture request bodies too | No |
|
|
157
|
-
| `NETWORK_DOWNLOAD_DIR` | `./downloads` | Download directory | No |
|
|
158
|
-
| `NETWORK_MAX_DOWNLOAD_SIZE` | `104857600` | Max download size (bytes, default 100MB) | No |
|
|
159
|
-
| `NETWORK_DOWNLOAD_ENABLED` | `false` | Enable file downloads (`browser_download` tool) | No |
|
|
160
|
-
| `NETWORK_SAVE_ENABLED` | `false` | Enable network capture save (`network_save` tool) | No |
|
|
161
|
-
|
|
162
|
-
### Rate Limiting
|
|
163
|
-
|
|
164
|
-
| Variable | Default | Description | Required |
|
|
165
|
-
|----------|---------|-------------|----------|
|
|
166
|
-
| `RATE_LIMIT_ENABLED` | `true` | Enable rate limiting | No |
|
|
167
|
-
| `RATE_LIMIT_GLOBAL_RPM` | `120` | Global requests per minute | No |
|
|
168
|
-
| `RATE_LIMIT_PER_TOOL_RPM` | `30` | Per-tool requests per minute | No |
|
|
169
|
-
| `RATE_LIMIT_BURST_SIZE` | `10` | Max burst size | No |
|
|
170
|
-
|
|
171
|
-
### Cache
|
|
172
|
-
|
|
173
|
-
| Variable | Default | Description | Required |
|
|
174
|
-
|----------|---------|-------------|----------|
|
|
175
|
-
| `CACHE_MAX_ENTRIES` | `100` | Max cache entries | No |
|
|
176
|
-
| `CACHE_TTL_SECONDS` | `300` | Cache TTL (seconds) | No |
|
|
177
|
-
|
|
178
|
-
### Security
|
|
179
|
-
|
|
180
|
-
| Variable | Default | Description | Required |
|
|
181
|
-
|----------|---------|-------------|----------|
|
|
182
|
-
| `SECURITY_API_KEY` | `""` | API key for authentication (empty = auth disabled) | No |
|
|
183
|
-
| `SECURITY_ALLOWED_DIRS` | `[]` | Allowed directories for file access (JSON array) | No |
|
|
184
|
-
| `SECURITY_MAX_MEMORY_MB` | `512` | Max memory usage (MB) | No |
|
|
185
|
-
| `SECURITY_DEFAULT_TIMEOUT` | `30000` | Default operation timeout (ms) | No |
|
|
186
|
-
| `SECURITY_MAX_TIMEOUT` | `120000` | Max timeout (ms) | No |
|
|
187
|
-
| `SECURITY_MAX_SESSIONS` | `10` | Max concurrent browser sessions | No |
|
|
188
|
-
|
|
189
|
-
### Config
|
|
190
|
-
|
|
191
|
-
| Variable | Default | Description | Required |
|
|
192
|
-
|----------|---------|-------------|----------|
|
|
193
|
-
| `BROWSER_MCP_CONFIG` | — | Config file path (JSON) | No |
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## All Tools
|
|
198
|
-
|
|
199
|
-
### Navigation (5)
|
|
200
|
-
|
|
201
|
-
| Tool | Description |
|
|
202
|
-
|------|-------------|
|
|
203
|
-
| `browser_navigate` | Navigate to a URL |
|
|
204
|
-
| `browser_go_back` | Go back in history |
|
|
205
|
-
| `browser_go_forward` | Go forward in history |
|
|
206
|
-
| `browser_refresh` | Refresh the current page |
|
|
207
|
-
| `browser_wait_for` | Wait for a specified timeout |
|
|
208
|
-
|
|
209
|
-
### Interaction (8)
|
|
210
|
-
|
|
211
|
-
| Tool | Description |
|
|
212
|
-
|------|-------------|
|
|
213
|
-
| `browser_click` | Click an element by CSS selector |
|
|
214
|
-
| `browser_fill` | Fill text into an input field |
|
|
215
|
-
| `browser_select` | Select option(s) in a dropdown |
|
|
216
|
-
| `browser_hover` | Hover over an element |
|
|
217
|
-
| `browser_drag` | Drag and drop an element |
|
|
218
|
-
| `browser_type` | Type text character by character |
|
|
219
|
-
| `browser_press_key` | Press a keyboard key |
|
|
220
|
-
| `browser_file_upload` | Upload files via file input |
|
|
221
|
-
|
|
222
|
-
### Extraction (7)
|
|
223
|
-
|
|
224
|
-
| Tool | Description |
|
|
225
|
-
|------|-------------|
|
|
226
|
-
| `browser_extract_html` | Extract full page HTML |
|
|
227
|
-
| `browser_extract_markdown` | Extract page as approximate markdown |
|
|
228
|
-
| `browser_extract_text` | Extract visible text |
|
|
229
|
-
| `browser_extract_with_css` | Extract data matching a CSS selector |
|
|
230
|
-
| `browser_extract_table` | Extract tables as structured JSON |
|
|
231
|
-
| `browser_extract_schema_org` | Extract Schema.org JSON-LD data |
|
|
232
|
-
| `browser_extract_open_graph` | Extract Open Graph meta tags |
|
|
233
|
-
|
|
234
|
-
### Network (10)
|
|
235
|
-
|
|
236
|
-
| Tool | Description |
|
|
237
|
-
|------|-------------|
|
|
238
|
-
| `browser_network_requests` | List network requests made by the page |
|
|
239
|
-
| `browser_network_response` | Get full response details for a request |
|
|
240
|
-
| `browser_get_console` | Get console messages from the page |
|
|
241
|
-
| `browser_handle_dialog` | Accept or dismiss a browser dialog |
|
|
242
|
-
| `browser_wait_for_navigation` | Wait for the page to navigate |
|
|
243
|
-
| `browser_get_network_entries` | List detailed network entries with timing/sizes/headers |
|
|
244
|
-
| `browser_network_export` | Export network log to HAR, JSON, or CSV |
|
|
245
|
-
| `browser_websocket_frames` | List captured WebSocket frames |
|
|
246
|
-
| `browser_network_clear` | Clear captured network data |
|
|
247
|
-
| `browser_network_save` | Save network response or WS frames to disk |
|
|
248
|
-
|
|
249
|
-
### Browser Control (9)
|
|
250
|
-
|
|
251
|
-
| Tool | Description |
|
|
252
|
-
|------|-------------|
|
|
253
|
-
| `browser_screenshot` | Take a screenshot (page or element) |
|
|
254
|
-
| `browser_page_info` | Get page title, URL, viewport info |
|
|
255
|
-
| `browser_get_cookies` | Get all cookies |
|
|
256
|
-
| `browser_set_cookie` | Set a cookie |
|
|
257
|
-
| `browser_delete_cookie` | Delete a cookie by name |
|
|
258
|
-
| `browser_evaluate` | Execute JavaScript in page context |
|
|
259
|
-
| `browser_pdf` | Generate a PDF of the current page |
|
|
260
|
-
| `browser_download` | Download a URL to disk |
|
|
261
|
-
| `browser_scroll` | Scroll the page or an element |
|
|
262
|
-
|
|
263
|
-
### Session (3)
|
|
264
|
-
|
|
265
|
-
| Tool | Description |
|
|
266
|
-
|------|-------------|
|
|
267
|
-
| `browser_open_session` | Open a new browser session (tab) |
|
|
268
|
-
| `browser_close_session` | Close a session by ID |
|
|
269
|
-
| `browser_list_sessions` | List all active sessions |
|
|
270
|
-
|
|
271
|
-
### Admin (3)
|
|
272
|
-
|
|
273
|
-
| Tool | Description |
|
|
274
|
-
|------|-------------|
|
|
275
|
-
| `browser_server_status` | Server status, version, session/cache stats |
|
|
276
|
-
| `browser_cache_stats` | Cache statistics (hits, misses, size) |
|
|
277
|
-
| `browser_clear_cache` | Clear the entire result cache |
|
|
278
|
-
|
|
279
|
-
### Reverse Engineering (4)
|
|
280
|
-
|
|
281
|
-
| Tool | Description |
|
|
282
|
-
|------|-------------|
|
|
283
|
-
| `browser_js_beautify` | Beautify and format JavaScript code |
|
|
284
|
-
| `browser_js_deobfuscate` | Deobfuscate JS (hex, unicode, base64) |
|
|
285
|
-
| `browser_api_discover` | Discover API endpoints in JS source |
|
|
286
|
-
| `browser_auth_analyze` | Analyze network logs for auth flows |
|
|
287
|
-
|
|
288
|
-
### Stealth (2)
|
|
289
|
-
|
|
290
|
-
| Tool | Description |
|
|
291
|
-
|------|-------------|
|
|
292
|
-
| `browser_fingerprint` | Generate randomized browser fingerprint |
|
|
293
|
-
| `browser_human_behavior` | Generate human-like typing/mouse/scroll profiles |
|
|
294
|
-
|
|
295
|
-
**Total: 51 tools across 9 categories, production-grade architecture**
|
|
296
|
-
|
|
297
|
-
---
|
|
298
|
-
|
|
299
|
-
## Use Cases
|
|
300
|
-
|
|
301
|
-
- **Reverse Engineering** — Deobfuscate JavaScript, uncover API endpoints, map auth flows, export HAR for offline analysis
|
|
302
|
-
- **Web Scraping** — Extract HTML, Markdown, structured data (Schema.org, Open Graph, tables) from any browser-accessible page
|
|
303
|
-
- **Network Monitoring** — Intercept HTTP/HTTPS traffic in real time, inspect WebSocket frames, save binary bodies to disk
|
|
304
|
-
- **Form Automation** — Login flows, multi-step forms, file uploads, dropdown selections — all driven by AI
|
|
305
|
-
- **Session Management** — Isolated concurrent browser sessions with automatic TTL cleanup
|
|
306
|
-
- **Data Export** — Network captures in HAR/JSON/CSV, body saves, WebSocket frame logs (.jsonl)
|
|
307
|
-
|
|
308
|
-
---
|
|
309
|
-
|
|
310
|
-
## Security
|
|
311
|
-
|
|
312
|
-
- `redirect: 'manual'` on all URL fetches — SSRF redirect bypass protection
|
|
313
|
-
- `validateUrlAsync` with DNS lookup — DNS rebind attack prevention
|
|
314
|
-
- `DANGEROUS_EXTENSIONS` blocklist (`.exe`, `.bat`, `.sh` etc.) → safe `.bin` fallback
|
|
315
|
-
- Pseudo-FS path blocking (`/proc/`, `/sys/`, `/etc/` etc.) — path traversal prevention
|
|
316
|
-
- Cookie header filter — cross-origin credential leakage prevention in HTTP re-fetch
|
|
317
|
-
- `NETWORK_DOWNLOAD_ENABLED` and `NETWORK_SAVE_ENABLED` default to **false** — must be explicitly enabled
|
|
318
|
-
- Input sanitization — null byte, path traversal, fileName injection guards
|
|
319
|
-
- Rate limiting — token bucket algorithm, global + per-tool, configurable RPM
|
|
320
|
-
- LRU cache with TTL — bounded memory usage
|
|
321
|
-
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
## Development
|
|
325
|
-
|
|
326
|
-
```bash
|
|
327
|
-
# Test
|
|
328
|
-
npm test
|
|
329
|
-
npm run test:coverage
|
|
330
|
-
|
|
331
|
-
# Type check (tsc --noEmit)
|
|
332
|
-
npm run lint
|
|
333
|
-
|
|
334
|
-
# Build
|
|
335
|
-
npm run build
|
|
336
|
-
```
|
|
337
|
-
|
|
338
|
-
---
|
|
339
|
-
|
|
340
|
-
## Roadmap
|
|
341
|
-
|
|
342
|
-
- **New tools**: PDF extraction, screenshot annotation, form detection, cookie manager, session snapshot/restore
|
|
343
|
-
- **Cloudflare bypass**: Playwright Stealth integration, rotatable proxy support
|
|
344
|
-
- **Batch scraping**: Multi-page scraping pipeline, queue system
|
|
345
|
-
- **Performance**: Ring buffer optimization, streaming responses, lazy evaluation
|
|
346
|
-
- **Developer Experience**: Interactive CLI, playground UI, type-safe client SDK
|
|
347
|
-
|
|
348
|
-
---
|
|
349
|
-
|
|
350
|
-
## 🇹🇷 Türkçe
|
|
351
|
-
|
|
352
|
-
**`@natchs/browser-mcp`** — reverse engineering, web scraping, network interception ve HAR export için tasarlanmış, AI ajanların tarayıcıyı tam kontrol etmesini sağlayan bir Model Context Protocol sunucusu.
|
|
353
|
-
|
|
354
|
-
```bash
|
|
355
|
-
npm install @natchs/browser-mcp
|
|
356
|
-
npx @natchs/browser-mcp
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
Üç browser modu: `fresh` (izole), `persistent` (gerçek Chrome profilin, otomatik tespit), `connect` (mevcut Chrome'a bağlan). 50+ araç, 9 kategori, kurumsal güvenlik.
|
|
360
|
-
|
|
361
|
-
Detaylı bilgi için yukarıdaki İngilizce dokümantasyonu inceleyin.
|
|
362
|
-
|
|
363
|
-
---
|
|
364
|
-
|
|
365
|
-
## License
|
|
366
|
-
|
|
367
|
-
MIT
|
|
1
|
+
# @natchs/browser-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@natchs/browser-mcp)
|
|
4
|
+
[](LICENSE)
|
|
5
|
+
[](package.json)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Your AI Agent's Browser Superpowers — Reverse Engineering, Network Interception & Full Browser Control
|
|
10
|
+
|
|
11
|
+
**`@natchs/browser-mcp`** is a Model Context Protocol server that gives AI agents **complete browser control** — navigate, click, scrape, intercept network traffic, export HAR files, capture WebSocket frames, deobfuscate JavaScript, and more. All through a single MCP interface.
|
|
12
|
+
|
|
13
|
+
Three browser modes (fresh / persistent / connect), production-grade security, 50+ tools, 9 categories. Built for reverse engineers, data extraction pipelines, and AI-powered automation.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Features
|
|
18
|
+
|
|
19
|
+
- 🔍 **Reverse Engineering Toolkit** — JS beautify/deobfuscate, API endpoint discovery, auth flow analysis
|
|
20
|
+
- 🌐 **Web Scraping** — HTML, Markdown, text, CSS selectors, tables, Schema.org JSON-LD, Open Graph
|
|
21
|
+
- 📡 **Network Intelligence** — Real-time HTTP/HTTPS interception, WebSocket frame capture, HAR/JSON/CSV export
|
|
22
|
+
- 🕶️ **Stealth Mode** — Fingerprint rotation, human behavior simulation
|
|
23
|
+
- 🔐 **Enterprise Security** — SSRF protection, DNS rebind prevention, path traversal guards, cookie leak prevention
|
|
24
|
+
- 🧩 **3 Browser Profiles** — Fresh (isolated), Persistent (your Chrome profile, auto-detected), Connect (existing browser)
|
|
25
|
+
- 📦 **50+ Tools** — Navigation, interaction, extraction, network, browser control, sessions, admin, RE, stealth
|
|
26
|
+
- ⚡ **Production Ready** — Rate limiting, LRU cache, structured logging, metrics, plugin system, configurable timeouts
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Install
|
|
34
|
+
npm install @natchs/browser-mcp
|
|
35
|
+
|
|
36
|
+
# Run (Chromium installs automatically ~30s on first run)
|
|
37
|
+
npx @natchs/browser-mcp
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### MCP Client Config
|
|
41
|
+
|
|
42
|
+
Add to Claude Desktop, Cursor, VS Code (Cline, Roo Code), Continue.dev, or any MCP-compatible client:
|
|
43
|
+
|
|
44
|
+
```json
|
|
45
|
+
{
|
|
46
|
+
"mcpServers": {
|
|
47
|
+
"browser-mcp": {
|
|
48
|
+
"command": "npx",
|
|
49
|
+
"args": ["@natchs/browser-mcp"]
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Local Build
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
git clone https://github.com/natchs/browser-mcp.git
|
|
59
|
+
cd browser-mcp
|
|
60
|
+
npm ci
|
|
61
|
+
npm run build
|
|
62
|
+
npx @natchs/browser-mcp
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Browser Modes
|
|
68
|
+
|
|
69
|
+
The `BROWSER_MODE` environment variable controls which browser profile the agent uses:
|
|
70
|
+
|
|
71
|
+
| Mode | Description | Best For |
|
|
72
|
+
|------|-------------|----------|
|
|
73
|
+
| `fresh` (default) | Playwright's own Chromium. Fresh profile every time — no cookies, history, or extensions carried over | Clean room analysis, leave-no-trace operations |
|
|
74
|
+
| `persistent` | **Your real Chrome profile.** Auto-detected since v2.3.0. All cookies, sessions, extensions, and logged-in accounts available to the agent | When the agent needs to act "as you" — Gmail, GitHub, ChatGPT, corporate portals |
|
|
75
|
+
| `connect` | Attaches to your already-running Chrome via CDP debug port | Hybrid workflows — manually drive Chrome while the agent assists |
|
|
76
|
+
|
|
77
|
+
### Persistent (auto-detect)
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
BROWSER_MODE=persistent npx @natchs/browser-mcp
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Since v2.3.0 the Chrome profile is auto-detected on Windows/macOS/Linux. No path needed. To specify a manual path:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
BROWSER_MODE=persistent BROWSER_USER_DATA_DIR=C:\Users\...\User Data\Default npx @natchs/browser-mcp
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Connect (attach to existing Chrome)
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
# Start Chrome with debug port first:
|
|
93
|
+
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
|
|
94
|
+
|
|
95
|
+
# Then launch the agent:
|
|
96
|
+
BROWSER_MODE=connect npx @natchs/browser-mcp
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Per-Mode Client Profiles
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"mcpServers": {
|
|
104
|
+
"browser-mcp-persistent": {
|
|
105
|
+
"command": "npx",
|
|
106
|
+
"args": ["@natchs/browser-mcp"],
|
|
107
|
+
"env": { "BROWSER_MODE": "persistent" }
|
|
108
|
+
},
|
|
109
|
+
"browser-mcp-fresh": {
|
|
110
|
+
"command": "npx",
|
|
111
|
+
"args": ["@natchs/browser-mcp"],
|
|
112
|
+
"env": { "BROWSER_MODE": "fresh" }
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Environment Variables
|
|
121
|
+
|
|
122
|
+
All configuration is managed through environment variables.
|
|
123
|
+
|
|
124
|
+
### Browser
|
|
125
|
+
|
|
126
|
+
| Variable | Default | Description | Required |
|
|
127
|
+
|----------|---------|-------------|----------|
|
|
128
|
+
| `BROWSER_MODE` | `fresh` | Browser mode: `fresh`, `persistent`, `connect` | No |
|
|
129
|
+
| `BROWSER_HEADLESS` | `true` | Run in headless mode (`true`/`false`/`1`/`0`/`yes`/`no`) | No |
|
|
130
|
+
| `BROWSER_USER_DATA_DIR` | — | Chrome user data directory (absolute path) | No |
|
|
131
|
+
| `BROWSER_CHANNEL` | `""` | Browser channel (`chrome`, `msedge`, `chromium`, etc.) | No |
|
|
132
|
+
| `BROWSER_DEBUG_PORT` | `9222` | CDP debug port number | No |
|
|
133
|
+
| `BROWSER_AUTO_DETECT_PROFILE` | `true` | Auto-detect Chrome profile location | No |
|
|
134
|
+
| `BROWSER_VIEWPORT_WIDTH` | `1280` | Viewport width (px) | No |
|
|
135
|
+
| `BROWSER_VIEWPORT_HEIGHT` | `720` | Viewport height (px) | No |
|
|
136
|
+
| `BROWSER_USER_AGENT` | — | Custom User-Agent string | No |
|
|
137
|
+
| `BROWSER_LOCALE` | — | Browser locale (e.g. `en-US`) | No |
|
|
138
|
+
| `BROWSER_TIMEOUT` | `30000` | Browser operation timeout (ms) | No |
|
|
139
|
+
| `BROWSER_AUTO_INSTALL` | `true` | Auto-install Chromium (`false` to disable) | No |
|
|
140
|
+
|
|
141
|
+
### Network & Download
|
|
142
|
+
|
|
143
|
+
| Variable | Default | Description | Required |
|
|
144
|
+
|----------|---------|-------------|----------|
|
|
145
|
+
| `NETWORK_HAR_ENABLED` | `1` | Enable HAR capture (`0` to disable) | No |
|
|
146
|
+
| `NETWORK_MAX_ENTRIES` | `5000` | Max network entries stored | No |
|
|
147
|
+
| `NETWORK_MAX_RESPONSE_BODY_SIZE` | `262144` | Max response body size (bytes) | No |
|
|
148
|
+
| `NETWORK_STORE_RESPONSE_BODIES` | `false` | Keep response bodies in memory | No |
|
|
149
|
+
| `NETWORK_EXCLUDE_BODY_TYPES` | `["image","media","font","stylesheet"]` | Body types excluded from storage (JSON array) | No |
|
|
150
|
+
| `NETWORK_EXPORT_DIR` | `./network-logs` | Network log export directory | No |
|
|
151
|
+
| `NETWORK_CAPTURE_FAILED` | `true` | Capture failed requests too | No |
|
|
152
|
+
| `NETWORK_CAPTURE_WS` | `true` | Capture WebSocket frames | No |
|
|
153
|
+
| `NETWORK_WS_MAX_FRAMES` | `1000` | Max WebSocket frames stored | No |
|
|
154
|
+
| `NETWORK_WS_MAX_FRAME_SIZE` | `65536` | Max WebSocket frame payload (bytes) | No |
|
|
155
|
+
| `NETWORK_MAX_MEMORY_MB` | `256` | Max memory for network capture (MB) | No |
|
|
156
|
+
| `NETWORK_CAPTURE_REQUEST_BODY` | `false` | Capture request bodies too | No |
|
|
157
|
+
| `NETWORK_DOWNLOAD_DIR` | `./downloads` | Download directory | No |
|
|
158
|
+
| `NETWORK_MAX_DOWNLOAD_SIZE` | `104857600` | Max download size (bytes, default 100MB) | No |
|
|
159
|
+
| `NETWORK_DOWNLOAD_ENABLED` | `false` | Enable file downloads (`browser_download` tool) | No |
|
|
160
|
+
| `NETWORK_SAVE_ENABLED` | `false` | Enable network capture save (`network_save` tool) | No |
|
|
161
|
+
|
|
162
|
+
### Rate Limiting
|
|
163
|
+
|
|
164
|
+
| Variable | Default | Description | Required |
|
|
165
|
+
|----------|---------|-------------|----------|
|
|
166
|
+
| `RATE_LIMIT_ENABLED` | `true` | Enable rate limiting | No |
|
|
167
|
+
| `RATE_LIMIT_GLOBAL_RPM` | `120` | Global requests per minute | No |
|
|
168
|
+
| `RATE_LIMIT_PER_TOOL_RPM` | `30` | Per-tool requests per minute | No |
|
|
169
|
+
| `RATE_LIMIT_BURST_SIZE` | `10` | Max burst size | No |
|
|
170
|
+
|
|
171
|
+
### Cache
|
|
172
|
+
|
|
173
|
+
| Variable | Default | Description | Required |
|
|
174
|
+
|----------|---------|-------------|----------|
|
|
175
|
+
| `CACHE_MAX_ENTRIES` | `100` | Max cache entries | No |
|
|
176
|
+
| `CACHE_TTL_SECONDS` | `300` | Cache TTL (seconds) | No |
|
|
177
|
+
|
|
178
|
+
### Security
|
|
179
|
+
|
|
180
|
+
| Variable | Default | Description | Required |
|
|
181
|
+
|----------|---------|-------------|----------|
|
|
182
|
+
| `SECURITY_API_KEY` | `""` | API key for authentication (empty = auth disabled) | No |
|
|
183
|
+
| `SECURITY_ALLOWED_DIRS` | `[]` | Allowed directories for file access (JSON array) | No |
|
|
184
|
+
| `SECURITY_MAX_MEMORY_MB` | `512` | Max memory usage (MB) | No |
|
|
185
|
+
| `SECURITY_DEFAULT_TIMEOUT` | `30000` | Default operation timeout (ms) | No |
|
|
186
|
+
| `SECURITY_MAX_TIMEOUT` | `120000` | Max timeout (ms) | No |
|
|
187
|
+
| `SECURITY_MAX_SESSIONS` | `10` | Max concurrent browser sessions | No |
|
|
188
|
+
|
|
189
|
+
### Config
|
|
190
|
+
|
|
191
|
+
| Variable | Default | Description | Required |
|
|
192
|
+
|----------|---------|-------------|----------|
|
|
193
|
+
| `BROWSER_MCP_CONFIG` | — | Config file path (JSON) | No |
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## All Tools
|
|
198
|
+
|
|
199
|
+
### Navigation (5)
|
|
200
|
+
|
|
201
|
+
| Tool | Description |
|
|
202
|
+
|------|-------------|
|
|
203
|
+
| `browser_navigate` | Navigate to a URL |
|
|
204
|
+
| `browser_go_back` | Go back in history |
|
|
205
|
+
| `browser_go_forward` | Go forward in history |
|
|
206
|
+
| `browser_refresh` | Refresh the current page |
|
|
207
|
+
| `browser_wait_for` | Wait for a specified timeout |
|
|
208
|
+
|
|
209
|
+
### Interaction (8)
|
|
210
|
+
|
|
211
|
+
| Tool | Description |
|
|
212
|
+
|------|-------------|
|
|
213
|
+
| `browser_click` | Click an element by CSS selector |
|
|
214
|
+
| `browser_fill` | Fill text into an input field |
|
|
215
|
+
| `browser_select` | Select option(s) in a dropdown |
|
|
216
|
+
| `browser_hover` | Hover over an element |
|
|
217
|
+
| `browser_drag` | Drag and drop an element |
|
|
218
|
+
| `browser_type` | Type text character by character |
|
|
219
|
+
| `browser_press_key` | Press a keyboard key |
|
|
220
|
+
| `browser_file_upload` | Upload files via file input |
|
|
221
|
+
|
|
222
|
+
### Extraction (7)
|
|
223
|
+
|
|
224
|
+
| Tool | Description |
|
|
225
|
+
|------|-------------|
|
|
226
|
+
| `browser_extract_html` | Extract full page HTML |
|
|
227
|
+
| `browser_extract_markdown` | Extract page as approximate markdown |
|
|
228
|
+
| `browser_extract_text` | Extract visible text |
|
|
229
|
+
| `browser_extract_with_css` | Extract data matching a CSS selector |
|
|
230
|
+
| `browser_extract_table` | Extract tables as structured JSON |
|
|
231
|
+
| `browser_extract_schema_org` | Extract Schema.org JSON-LD data |
|
|
232
|
+
| `browser_extract_open_graph` | Extract Open Graph meta tags |
|
|
233
|
+
|
|
234
|
+
### Network (10)
|
|
235
|
+
|
|
236
|
+
| Tool | Description |
|
|
237
|
+
|------|-------------|
|
|
238
|
+
| `browser_network_requests` | List network requests made by the page |
|
|
239
|
+
| `browser_network_response` | Get full response details for a request |
|
|
240
|
+
| `browser_get_console` | Get console messages from the page |
|
|
241
|
+
| `browser_handle_dialog` | Accept or dismiss a browser dialog |
|
|
242
|
+
| `browser_wait_for_navigation` | Wait for the page to navigate |
|
|
243
|
+
| `browser_get_network_entries` | List detailed network entries with timing/sizes/headers |
|
|
244
|
+
| `browser_network_export` | Export network log to HAR, JSON, or CSV |
|
|
245
|
+
| `browser_websocket_frames` | List captured WebSocket frames |
|
|
246
|
+
| `browser_network_clear` | Clear captured network data |
|
|
247
|
+
| `browser_network_save` | Save network response or WS frames to disk |
|
|
248
|
+
|
|
249
|
+
### Browser Control (9)
|
|
250
|
+
|
|
251
|
+
| Tool | Description |
|
|
252
|
+
|------|-------------|
|
|
253
|
+
| `browser_screenshot` | Take a screenshot (page or element) |
|
|
254
|
+
| `browser_page_info` | Get page title, URL, viewport info |
|
|
255
|
+
| `browser_get_cookies` | Get all cookies |
|
|
256
|
+
| `browser_set_cookie` | Set a cookie |
|
|
257
|
+
| `browser_delete_cookie` | Delete a cookie by name |
|
|
258
|
+
| `browser_evaluate` | Execute JavaScript in page context |
|
|
259
|
+
| `browser_pdf` | Generate a PDF of the current page |
|
|
260
|
+
| `browser_download` | Download a URL to disk |
|
|
261
|
+
| `browser_scroll` | Scroll the page or an element |
|
|
262
|
+
|
|
263
|
+
### Session (3)
|
|
264
|
+
|
|
265
|
+
| Tool | Description |
|
|
266
|
+
|------|-------------|
|
|
267
|
+
| `browser_open_session` | Open a new browser session (tab) |
|
|
268
|
+
| `browser_close_session` | Close a session by ID |
|
|
269
|
+
| `browser_list_sessions` | List all active sessions |
|
|
270
|
+
|
|
271
|
+
### Admin (3)
|
|
272
|
+
|
|
273
|
+
| Tool | Description |
|
|
274
|
+
|------|-------------|
|
|
275
|
+
| `browser_server_status` | Server status, version, session/cache stats |
|
|
276
|
+
| `browser_cache_stats` | Cache statistics (hits, misses, size) |
|
|
277
|
+
| `browser_clear_cache` | Clear the entire result cache |
|
|
278
|
+
|
|
279
|
+
### Reverse Engineering (4)
|
|
280
|
+
|
|
281
|
+
| Tool | Description |
|
|
282
|
+
|------|-------------|
|
|
283
|
+
| `browser_js_beautify` | Beautify and format JavaScript code |
|
|
284
|
+
| `browser_js_deobfuscate` | Deobfuscate JS (hex, unicode, base64) |
|
|
285
|
+
| `browser_api_discover` | Discover API endpoints in JS source |
|
|
286
|
+
| `browser_auth_analyze` | Analyze network logs for auth flows |
|
|
287
|
+
|
|
288
|
+
### Stealth (2)
|
|
289
|
+
|
|
290
|
+
| Tool | Description |
|
|
291
|
+
|------|-------------|
|
|
292
|
+
| `browser_fingerprint` | Generate randomized browser fingerprint |
|
|
293
|
+
| `browser_human_behavior` | Generate human-like typing/mouse/scroll profiles |
|
|
294
|
+
|
|
295
|
+
**Total: 51 tools across 9 categories, production-grade architecture**
|
|
296
|
+
|
|
297
|
+
---
|
|
298
|
+
|
|
299
|
+
## Use Cases
|
|
300
|
+
|
|
301
|
+
- **Reverse Engineering** — Deobfuscate JavaScript, uncover API endpoints, map auth flows, export HAR for offline analysis
|
|
302
|
+
- **Web Scraping** — Extract HTML, Markdown, structured data (Schema.org, Open Graph, tables) from any browser-accessible page
|
|
303
|
+
- **Network Monitoring** — Intercept HTTP/HTTPS traffic in real time, inspect WebSocket frames, save binary bodies to disk
|
|
304
|
+
- **Form Automation** — Login flows, multi-step forms, file uploads, dropdown selections — all driven by AI
|
|
305
|
+
- **Session Management** — Isolated concurrent browser sessions with automatic TTL cleanup
|
|
306
|
+
- **Data Export** — Network captures in HAR/JSON/CSV, body saves, WebSocket frame logs (.jsonl)
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## Security
|
|
311
|
+
|
|
312
|
+
- `redirect: 'manual'` on all URL fetches — SSRF redirect bypass protection
|
|
313
|
+
- `validateUrlAsync` with DNS lookup — DNS rebind attack prevention
|
|
314
|
+
- `DANGEROUS_EXTENSIONS` blocklist (`.exe`, `.bat`, `.sh` etc.) → safe `.bin` fallback
|
|
315
|
+
- Pseudo-FS path blocking (`/proc/`, `/sys/`, `/etc/` etc.) — path traversal prevention
|
|
316
|
+
- Cookie header filter — cross-origin credential leakage prevention in HTTP re-fetch
|
|
317
|
+
- `NETWORK_DOWNLOAD_ENABLED` and `NETWORK_SAVE_ENABLED` default to **false** — must be explicitly enabled
|
|
318
|
+
- Input sanitization — null byte, path traversal, fileName injection guards
|
|
319
|
+
- Rate limiting — token bucket algorithm, global + per-tool, configurable RPM
|
|
320
|
+
- LRU cache with TTL — bounded memory usage
|
|
321
|
+
|
|
322
|
+
---
|
|
323
|
+
|
|
324
|
+
## Development
|
|
325
|
+
|
|
326
|
+
```bash
|
|
327
|
+
# Test
|
|
328
|
+
npm test
|
|
329
|
+
npm run test:coverage
|
|
330
|
+
|
|
331
|
+
# Type check (tsc --noEmit)
|
|
332
|
+
npm run lint
|
|
333
|
+
|
|
334
|
+
# Build
|
|
335
|
+
npm run build
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Roadmap
|
|
341
|
+
|
|
342
|
+
- **New tools**: PDF extraction, screenshot annotation, form detection, cookie manager, session snapshot/restore
|
|
343
|
+
- **Cloudflare bypass**: Playwright Stealth integration, rotatable proxy support
|
|
344
|
+
- **Batch scraping**: Multi-page scraping pipeline, queue system
|
|
345
|
+
- **Performance**: Ring buffer optimization, streaming responses, lazy evaluation
|
|
346
|
+
- **Developer Experience**: Interactive CLI, playground UI, type-safe client SDK
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## 🇹🇷 Türkçe
|
|
351
|
+
|
|
352
|
+
**`@natchs/browser-mcp`** — reverse engineering, web scraping, network interception ve HAR export için tasarlanmış, AI ajanların tarayıcıyı tam kontrol etmesini sağlayan bir Model Context Protocol sunucusu.
|
|
353
|
+
|
|
354
|
+
```bash
|
|
355
|
+
npm install @natchs/browser-mcp
|
|
356
|
+
npx @natchs/browser-mcp
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
Üç browser modu: `fresh` (izole), `persistent` (gerçek Chrome profilin, otomatik tespit), `connect` (mevcut Chrome'a bağlan). 50+ araç, 9 kategori, kurumsal güvenlik.
|
|
360
|
+
|
|
361
|
+
Detaylı bilgi için yukarıdaki İngilizce dokümantasyonu inceleyin.
|
|
362
|
+
|
|
363
|
+
---
|
|
364
|
+
|
|
365
|
+
## License
|
|
366
|
+
|
|
367
|
+
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@natchs/browser-mcp",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.7.0",
|
|
4
4
|
"description": "MCP server for browser automation — reverse engineering, web scraping, network interception, HAR export, WebSocket capture, SSRF-safe download tool. Three browser modes: fresh (isolated), persistent (your Chrome profile with auto-detect), connect (existing browser). AI agent controlled via Model Context Protocol.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|