mcp-cloakbrowser 0.1.0__tar.gz
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.
- mcp_cloakbrowser-0.1.0/.gitignore +14 -0
- mcp_cloakbrowser-0.1.0/LICENSE +21 -0
- mcp_cloakbrowser-0.1.0/PKG-INFO +206 -0
- mcp_cloakbrowser-0.1.0/README.md +180 -0
- mcp_cloakbrowser-0.1.0/README_CN.md +213 -0
- mcp_cloakbrowser-0.1.0/examples/hermes_config.yaml +21 -0
- mcp_cloakbrowser-0.1.0/pyproject.toml +41 -0
- mcp_cloakbrowser-0.1.0/skills/cloakbrowser-mcp/SKILL.md +160 -0
- mcp_cloakbrowser-0.1.0/src/cloakbrowser_mcp/__init__.py +3 -0
- mcp_cloakbrowser-0.1.0/src/cloakbrowser_mcp/__main__.py +4 -0
- mcp_cloakbrowser-0.1.0/src/cloakbrowser_mcp/browser_manager.py +129 -0
- mcp_cloakbrowser-0.1.0/src/cloakbrowser_mcp/server.py +397 -0
- mcp_cloakbrowser-0.1.0/src/cloakbrowser_mcp/tools.py +708 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MiwooMiwoo
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mcp-cloakbrowser
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for CloakBrowser - stealth browser automation via Model Context Protocol
|
|
5
|
+
Project-URL: Homepage, https://github.com/MiwooMiwoo/cloakbrowser-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/MiwooMiwoo/cloakbrowser-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/MiwooMiwoo/cloakbrowser-mcp/issues
|
|
8
|
+
Author: MiwooMiwoo
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: anti-detect,automation,browser,cloakbrowser,mcp,stealth
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: cloakbrowser>=0.3.0
|
|
24
|
+
Requires-Dist: mcp>=1.0.0
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# CloakBrowser MCP Server
|
|
28
|
+
|
|
29
|
+
[English](README.md) | [中文](README_CN.md)
|
|
30
|
+
|
|
31
|
+
> Stealth browser automation via [Model Context Protocol](https://modelcontextprotocol.io/), powered by [CloakBrowser](https://github.com/CloakHQ/CloakBrowser).
|
|
32
|
+
|
|
33
|
+
A drop-in MCP server that wraps CloakBrowser's stealth Chromium with **57 source-level C++ fingerprint patches** — not JS injection. Passes all 30/30 bot detection tests (reCAPTCHA v3 score: 0.9, Cloudflare Turnstile: PASS, FingerprintJS: PASS).
|
|
34
|
+
|
|
35
|
+
## Features
|
|
36
|
+
|
|
37
|
+
- **22 browser tools** — navigate, click, type, screenshot, console, evaluate JS, form filling, drag & drop, and more
|
|
38
|
+
- **Stealth by default** — `navigator.webdriver = false`, real Chrome TLS fingerprint, no CDP detection
|
|
39
|
+
- **Human-like behavior** — `humanize=True` enables Bézier mouse curves, per-character keyboard timing
|
|
40
|
+
- **Proxy support** — HTTP & SOCKS5 with GeoIP auto-detection
|
|
41
|
+
- **Session persistence** — save/load cookies and localStorage
|
|
42
|
+
- **Compatible with any MCP client** — Hermes Agent, Claude Desktop, Cursor, etc.
|
|
43
|
+
|
|
44
|
+
## Quick Start
|
|
45
|
+
|
|
46
|
+
### Install
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install cloakbrowser-mcp
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### Run
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# As a stdio MCP server
|
|
56
|
+
cloakbrowser-mcp
|
|
57
|
+
|
|
58
|
+
# Or directly
|
|
59
|
+
python -m cloakbrowser_mcp.server
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### Use with Hermes Agent
|
|
63
|
+
|
|
64
|
+
Add to `~/.hermes/config.yaml`:
|
|
65
|
+
|
|
66
|
+
```yaml
|
|
67
|
+
mcp_servers:
|
|
68
|
+
cloakbrowser:
|
|
69
|
+
command: "python"
|
|
70
|
+
args: ["-m", "cloakbrowser_mcp.server"]
|
|
71
|
+
timeout: 120
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Restart Hermes Agent. Tools will be registered as `mcp_cloakbrowser_browser_*`.
|
|
75
|
+
|
|
76
|
+
### Use with Claude Desktop
|
|
77
|
+
|
|
78
|
+
Add to `claude_desktop_config.json`:
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"cloakbrowser": {
|
|
84
|
+
"command": "cloakbrowser-mcp"
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## Available Tools
|
|
91
|
+
|
|
92
|
+
| Tool | Description |
|
|
93
|
+
|------|-------------|
|
|
94
|
+
| `browser_launch` | Launch a stealth CloakBrowser instance |
|
|
95
|
+
| `browser_close` | Close the browser and clean up |
|
|
96
|
+
| `browser_navigate` | Navigate to a URL, return compact snapshot |
|
|
97
|
+
| `browser_snapshot` | Get accessibility tree with ref IDs |
|
|
98
|
+
| `browser_click` | Click element by ref (e.g. `@e5`) |
|
|
99
|
+
| `browser_type` | Type text into input field by ref |
|
|
100
|
+
| `browser_press` | Press keyboard key (Enter, Tab, Escape...) |
|
|
101
|
+
| `browser_scroll` | Scroll page up/down |
|
|
102
|
+
| `browser_back` | Navigate back in history |
|
|
103
|
+
| `browser_forward` | Navigate forward in history |
|
|
104
|
+
| `browser_console` | Get console logs or evaluate JS |
|
|
105
|
+
| `browser_get_images` | List all images with URLs and alt text |
|
|
106
|
+
| `browser_screenshot` | Take PNG screenshot |
|
|
107
|
+
| `browser_wait_for` | Wait for element or text to appear |
|
|
108
|
+
| `browser_evaluate` | Evaluate JavaScript expression |
|
|
109
|
+
| `browser_get_content` | Get text/HTML of page or element |
|
|
110
|
+
| `browser_extract_links` | Extract all links as JSON |
|
|
111
|
+
| `browser_fill_form` | Fill multiple form fields at once |
|
|
112
|
+
| `browser_hover` | Hover over element by ref |
|
|
113
|
+
| `browser_select_option` | Select options in `<select>` elements |
|
|
114
|
+
| `browser_drag` | Drag element to another element |
|
|
115
|
+
| `browser_save_storage_state` | Save cookies/localStorage to file |
|
|
116
|
+
| `browser_load_storage_state` | Load cookies/localStorage from file |
|
|
117
|
+
| `browser_info` | Get current page URL, title, viewport |
|
|
118
|
+
|
|
119
|
+
## Tool Usage Examples
|
|
120
|
+
|
|
121
|
+
### Navigate and Interact
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
# Launch browser
|
|
125
|
+
await call_tool("browser_launch", {"headless": True, "humanize": True})
|
|
126
|
+
|
|
127
|
+
# Navigate to a page
|
|
128
|
+
await call_tool("browser_navigate", {"url": "https://example.com"})
|
|
129
|
+
|
|
130
|
+
# Get snapshot to see interactive elements
|
|
131
|
+
snapshot = await call_tool("browser_snapshot", {})
|
|
132
|
+
# Shows: [@e1] <a>Link text, [@e2] <input>[type: text]...
|
|
133
|
+
|
|
134
|
+
# Click a link
|
|
135
|
+
await call_tool("browser_click", {"ref": "@e1"})
|
|
136
|
+
|
|
137
|
+
# Type into search box
|
|
138
|
+
await call_tool("browser_type", {"ref": "@e2", "text": "hello world", "submit": True})
|
|
139
|
+
|
|
140
|
+
# Take screenshot
|
|
141
|
+
await call_tool("browser_screenshot", {})
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### Fill a Login Form
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
await call_tool("browser_fill_form", {
|
|
148
|
+
"fields": [
|
|
149
|
+
{"ref": "@e1", "value": "username"},
|
|
150
|
+
{"ref": "@e2", "value": "password123"},
|
|
151
|
+
],
|
|
152
|
+
"submit_ref": "@e3",
|
|
153
|
+
})
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### Advanced: Custom Fingerprint & Proxy
|
|
157
|
+
|
|
158
|
+
```python
|
|
159
|
+
await call_tool("browser_launch", {
|
|
160
|
+
"headless": True,
|
|
161
|
+
"humanize": True,
|
|
162
|
+
"proxy": "socks5://user:pass@proxy:1080",
|
|
163
|
+
"fingerprint_seed": "my-unique-seed-123",
|
|
164
|
+
"geoip": True,
|
|
165
|
+
"locale": "zh-CN",
|
|
166
|
+
})
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Save/Restore Session
|
|
170
|
+
|
|
171
|
+
```python
|
|
172
|
+
# Save session after login
|
|
173
|
+
await call_tool("browser_save_storage_state", {"path": "session.json"})
|
|
174
|
+
|
|
175
|
+
# Later: restore session
|
|
176
|
+
await call_tool("browser_load_storage_state", {"path": "session.json"})
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
## Architecture
|
|
180
|
+
|
|
181
|
+
```
|
|
182
|
+
MCP Client (Hermes/Claude/etc.)
|
|
183
|
+
│ stdio (JSON-RPC)
|
|
184
|
+
▼
|
|
185
|
+
cloakbrowser-mcp server
|
|
186
|
+
│
|
|
187
|
+
▼
|
|
188
|
+
CloakBrowser (Playwright-compatible API)
|
|
189
|
+
│
|
|
190
|
+
▼
|
|
191
|
+
Stealth Chromium (57 C++ patches)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The server maintains a single browser instance (singleton pattern). All tools operate on the current page. The browser is auto-launched on first tool call if not explicitly launched.
|
|
195
|
+
|
|
196
|
+
## Development
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
git clone https://github.com/MiwooMiwoo/cloakbrowser-mcp.git
|
|
200
|
+
cd cloakbrowser-mcp
|
|
201
|
+
pip install -e ".[dev]"
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## License
|
|
205
|
+
|
|
206
|
+
MIT
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# CloakBrowser MCP Server
|
|
2
|
+
|
|
3
|
+
[English](README.md) | [中文](README_CN.md)
|
|
4
|
+
|
|
5
|
+
> Stealth browser automation via [Model Context Protocol](https://modelcontextprotocol.io/), powered by [CloakBrowser](https://github.com/CloakHQ/CloakBrowser).
|
|
6
|
+
|
|
7
|
+
A drop-in MCP server that wraps CloakBrowser's stealth Chromium with **57 source-level C++ fingerprint patches** — not JS injection. Passes all 30/30 bot detection tests (reCAPTCHA v3 score: 0.9, Cloudflare Turnstile: PASS, FingerprintJS: PASS).
|
|
8
|
+
|
|
9
|
+
## Features
|
|
10
|
+
|
|
11
|
+
- **22 browser tools** — navigate, click, type, screenshot, console, evaluate JS, form filling, drag & drop, and more
|
|
12
|
+
- **Stealth by default** — `navigator.webdriver = false`, real Chrome TLS fingerprint, no CDP detection
|
|
13
|
+
- **Human-like behavior** — `humanize=True` enables Bézier mouse curves, per-character keyboard timing
|
|
14
|
+
- **Proxy support** — HTTP & SOCKS5 with GeoIP auto-detection
|
|
15
|
+
- **Session persistence** — save/load cookies and localStorage
|
|
16
|
+
- **Compatible with any MCP client** — Hermes Agent, Claude Desktop, Cursor, etc.
|
|
17
|
+
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
### Install
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pip install cloakbrowser-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### Run
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# As a stdio MCP server
|
|
30
|
+
cloakbrowser-mcp
|
|
31
|
+
|
|
32
|
+
# Or directly
|
|
33
|
+
python -m cloakbrowser_mcp.server
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### Use with Hermes Agent
|
|
37
|
+
|
|
38
|
+
Add to `~/.hermes/config.yaml`:
|
|
39
|
+
|
|
40
|
+
```yaml
|
|
41
|
+
mcp_servers:
|
|
42
|
+
cloakbrowser:
|
|
43
|
+
command: "python"
|
|
44
|
+
args: ["-m", "cloakbrowser_mcp.server"]
|
|
45
|
+
timeout: 120
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Restart Hermes Agent. Tools will be registered as `mcp_cloakbrowser_browser_*`.
|
|
49
|
+
|
|
50
|
+
### Use with Claude Desktop
|
|
51
|
+
|
|
52
|
+
Add to `claude_desktop_config.json`:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"cloakbrowser": {
|
|
58
|
+
"command": "cloakbrowser-mcp"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Available Tools
|
|
65
|
+
|
|
66
|
+
| Tool | Description |
|
|
67
|
+
|------|-------------|
|
|
68
|
+
| `browser_launch` | Launch a stealth CloakBrowser instance |
|
|
69
|
+
| `browser_close` | Close the browser and clean up |
|
|
70
|
+
| `browser_navigate` | Navigate to a URL, return compact snapshot |
|
|
71
|
+
| `browser_snapshot` | Get accessibility tree with ref IDs |
|
|
72
|
+
| `browser_click` | Click element by ref (e.g. `@e5`) |
|
|
73
|
+
| `browser_type` | Type text into input field by ref |
|
|
74
|
+
| `browser_press` | Press keyboard key (Enter, Tab, Escape...) |
|
|
75
|
+
| `browser_scroll` | Scroll page up/down |
|
|
76
|
+
| `browser_back` | Navigate back in history |
|
|
77
|
+
| `browser_forward` | Navigate forward in history |
|
|
78
|
+
| `browser_console` | Get console logs or evaluate JS |
|
|
79
|
+
| `browser_get_images` | List all images with URLs and alt text |
|
|
80
|
+
| `browser_screenshot` | Take PNG screenshot |
|
|
81
|
+
| `browser_wait_for` | Wait for element or text to appear |
|
|
82
|
+
| `browser_evaluate` | Evaluate JavaScript expression |
|
|
83
|
+
| `browser_get_content` | Get text/HTML of page or element |
|
|
84
|
+
| `browser_extract_links` | Extract all links as JSON |
|
|
85
|
+
| `browser_fill_form` | Fill multiple form fields at once |
|
|
86
|
+
| `browser_hover` | Hover over element by ref |
|
|
87
|
+
| `browser_select_option` | Select options in `<select>` elements |
|
|
88
|
+
| `browser_drag` | Drag element to another element |
|
|
89
|
+
| `browser_save_storage_state` | Save cookies/localStorage to file |
|
|
90
|
+
| `browser_load_storage_state` | Load cookies/localStorage from file |
|
|
91
|
+
| `browser_info` | Get current page URL, title, viewport |
|
|
92
|
+
|
|
93
|
+
## Tool Usage Examples
|
|
94
|
+
|
|
95
|
+
### Navigate and Interact
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
# Launch browser
|
|
99
|
+
await call_tool("browser_launch", {"headless": True, "humanize": True})
|
|
100
|
+
|
|
101
|
+
# Navigate to a page
|
|
102
|
+
await call_tool("browser_navigate", {"url": "https://example.com"})
|
|
103
|
+
|
|
104
|
+
# Get snapshot to see interactive elements
|
|
105
|
+
snapshot = await call_tool("browser_snapshot", {})
|
|
106
|
+
# Shows: [@e1] <a>Link text, [@e2] <input>[type: text]...
|
|
107
|
+
|
|
108
|
+
# Click a link
|
|
109
|
+
await call_tool("browser_click", {"ref": "@e1"})
|
|
110
|
+
|
|
111
|
+
# Type into search box
|
|
112
|
+
await call_tool("browser_type", {"ref": "@e2", "text": "hello world", "submit": True})
|
|
113
|
+
|
|
114
|
+
# Take screenshot
|
|
115
|
+
await call_tool("browser_screenshot", {})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Fill a Login Form
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
await call_tool("browser_fill_form", {
|
|
122
|
+
"fields": [
|
|
123
|
+
{"ref": "@e1", "value": "username"},
|
|
124
|
+
{"ref": "@e2", "value": "password123"},
|
|
125
|
+
],
|
|
126
|
+
"submit_ref": "@e3",
|
|
127
|
+
})
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### Advanced: Custom Fingerprint & Proxy
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
await call_tool("browser_launch", {
|
|
134
|
+
"headless": True,
|
|
135
|
+
"humanize": True,
|
|
136
|
+
"proxy": "socks5://user:pass@proxy:1080",
|
|
137
|
+
"fingerprint_seed": "my-unique-seed-123",
|
|
138
|
+
"geoip": True,
|
|
139
|
+
"locale": "zh-CN",
|
|
140
|
+
})
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### Save/Restore Session
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
# Save session after login
|
|
147
|
+
await call_tool("browser_save_storage_state", {"path": "session.json"})
|
|
148
|
+
|
|
149
|
+
# Later: restore session
|
|
150
|
+
await call_tool("browser_load_storage_state", {"path": "session.json"})
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Architecture
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
MCP Client (Hermes/Claude/etc.)
|
|
157
|
+
│ stdio (JSON-RPC)
|
|
158
|
+
▼
|
|
159
|
+
cloakbrowser-mcp server
|
|
160
|
+
│
|
|
161
|
+
▼
|
|
162
|
+
CloakBrowser (Playwright-compatible API)
|
|
163
|
+
│
|
|
164
|
+
▼
|
|
165
|
+
Stealth Chromium (57 C++ patches)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
The server maintains a single browser instance (singleton pattern). All tools operate on the current page. The browser is auto-launched on first tool call if not explicitly launched.
|
|
169
|
+
|
|
170
|
+
## Development
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
git clone https://github.com/MiwooMiwoo/cloakbrowser-mcp.git
|
|
174
|
+
cd cloakbrowser-mcp
|
|
175
|
+
pip install -e ".[dev]"
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## License
|
|
179
|
+
|
|
180
|
+
MIT
|
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# CloakBrowser MCP Server
|
|
2
|
+
|
|
3
|
+
[English](README.md) | [中文](README_CN.md)
|
|
4
|
+
|
|
5
|
+
> 基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的隐身浏览器自动化服务,由 [CloakBrowser](https://github.com/CloakHQ/CloakBrowser) 驱动。
|
|
6
|
+
|
|
7
|
+
一个即插即用的 MCP 服务器,封装了 CloakBrowser 的隐身 Chromium —— 通过 **57 个源码级 C++ 指纹补丁**(不是 JS 注入)实现浏览器伪装。通过所有 30 项反 bot 检测(reCAPTCHA v3 评分 0.9、Cloudflare Turnstile: PASS、FingerprintJS: PASS)。
|
|
8
|
+
|
|
9
|
+
## ✨ 特性
|
|
10
|
+
|
|
11
|
+
- **22 个浏览器工具** —— 导航、点击、输入、截图、控制台、JS 执行、表单填充、拖拽等
|
|
12
|
+
- **默认隐身** —— `navigator.webdriver = false`,真实 Chrome TLS 指纹,无 CDP 检测
|
|
13
|
+
- **人机行为模拟** —— `humanize=True` 启用贝塞尔鼠标曲线、逐字符键盘节奏
|
|
14
|
+
- **代理支持** —— HTTP / SOCKS5,支持 GeoIP 自动地理定位
|
|
15
|
+
- **会话持久化** —— 保存/加载 cookies 和 localStorage
|
|
16
|
+
- **兼容所有 MCP 客户端** —— Hermes Agent、Claude Desktop、Cursor 等
|
|
17
|
+
|
|
18
|
+
## 🚀 快速开始
|
|
19
|
+
|
|
20
|
+
### 安装
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
pip install cloakbrowser-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
### 运行
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# 作为 stdio MCP 服务器启动
|
|
30
|
+
cloakbrowser-mcp
|
|
31
|
+
|
|
32
|
+
# 或者直接运行
|
|
33
|
+
python -m cloakbrowser_mcp.server
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
### 配合 Hermes Agent 使用
|
|
37
|
+
|
|
38
|
+
编辑 `~/.hermes/config.yaml`,添加以下配置:
|
|
39
|
+
|
|
40
|
+
```yaml
|
|
41
|
+
mcp_servers:
|
|
42
|
+
cloakbrowser:
|
|
43
|
+
command: "python"
|
|
44
|
+
args: ["-m", "cloakbrowser_mcp.server"]
|
|
45
|
+
timeout: 120
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
重启 Hermes Agent 后,工具会自动注册为 `mcp_cloakbrowser_browser_*` 前缀。
|
|
49
|
+
|
|
50
|
+
### 配合 Claude Desktop 使用
|
|
51
|
+
|
|
52
|
+
编辑 `claude_desktop_config.json`:
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"mcpServers": {
|
|
57
|
+
"cloakbrowser": {
|
|
58
|
+
"command": "cloakbrowser-mcp"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## 📋 工具列表
|
|
65
|
+
|
|
66
|
+
| 工具名 | 说明 | 参数 |
|
|
67
|
+
|--------|------|------|
|
|
68
|
+
| `browser_launch` | 启动隐身 CloakBrowser 实例 | headless, humanize, proxy, fingerprint_seed, geoip, locale |
|
|
69
|
+
| `browser_close` | 关闭浏览器并清理资源 | 无 |
|
|
70
|
+
| `browser_navigate` | 导航到 URL,返回页面快照 | url, wait_until, humanize |
|
|
71
|
+
| `browser_snapshot` | 获取页面可访问性树(含 ref ID) | full |
|
|
72
|
+
| `browser_click` | 点击元素 | ref, button, click_count, humanize |
|
|
73
|
+
| `browser_type` | 在输入框中输入文本 | ref, text, submit, humanize |
|
|
74
|
+
| `browser_press` | 按下键盘按键 | key, humanize |
|
|
75
|
+
| `browser_scroll` | 滚动页面 | direction (up/down) |
|
|
76
|
+
| `browser_back` | 浏览器后退 | 无 |
|
|
77
|
+
| `browser_forward` | 浏览器前进 | 无 |
|
|
78
|
+
| `browser_console` | 获取控制台日志或执行 JS | expression, clear |
|
|
79
|
+
| `browser_get_images` | 列出页面所有图片 | 无 |
|
|
80
|
+
| `browser_screenshot` | 截取 PNG 截图 | save_path, full_page |
|
|
81
|
+
| `browser_wait_for` | 等待元素或文本出现 | selector, text, timeout |
|
|
82
|
+
| `browser_evaluate` | 执行 JavaScript 表达式 | expression |
|
|
83
|
+
| `browser_get_content` | 获取页面/元素的文本或 HTML | selector, format |
|
|
84
|
+
| `browser_extract_links` | 提取页面所有链接 | 无 |
|
|
85
|
+
| `browser_fill_form` | 批量填充表单字段 | fields, submit_ref |
|
|
86
|
+
| `browser_hover` | 鼠标悬停元素 | ref |
|
|
87
|
+
| `browser_select_option` | 选择下拉框选项 | ref, values |
|
|
88
|
+
| `browser_drag` | 拖拽元素到另一位置 | source_ref, target_ref |
|
|
89
|
+
| `browser_save_storage_state` | 保存 cookies/localStorage | path |
|
|
90
|
+
| `browser_load_storage_state` | 加载 cookies/localStorage | path |
|
|
91
|
+
| `browser_info` | 获取当前页面 URL、标题、视口 | 无 |
|
|
92
|
+
|
|
93
|
+
## 💡 使用示例
|
|
94
|
+
|
|
95
|
+
### 基本导航与交互
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
# 启动浏览器(隐身模式 + 人机模拟)
|
|
99
|
+
await call_tool("browser_launch", {"headless": True, "humanize": True})
|
|
100
|
+
|
|
101
|
+
# 导航到目标页面
|
|
102
|
+
await call_tool("browser_navigate", {"url": "https://example.com"})
|
|
103
|
+
|
|
104
|
+
# 获取页面快照,查看可交互元素
|
|
105
|
+
snapshot = await call_tool("browser_snapshot", {})
|
|
106
|
+
# 输出示例: [@e1] <a>链接文字, [@e2] <input>[type: text]...
|
|
107
|
+
|
|
108
|
+
# 点击链接
|
|
109
|
+
await call_tool("browser_click", {"ref": "@e1"})
|
|
110
|
+
|
|
111
|
+
# 在搜索框输入文字并回车
|
|
112
|
+
await call_tool("browser_type", {"ref": "@e2", "text": "你好世界", "submit": True})
|
|
113
|
+
|
|
114
|
+
# 截图保存
|
|
115
|
+
await call_tool("browser_screenshot", {"save_path": "result.png"})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### 填写登录表单
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
await call_tool("browser_fill_form", {
|
|
122
|
+
"fields": [
|
|
123
|
+
{"ref": "@e1", "value": "用户名"},
|
|
124
|
+
{"ref": "@e2", "value": "密码123"},
|
|
125
|
+
],
|
|
126
|
+
"submit_ref": "@e3", # 点击登录按钮
|
|
127
|
+
})
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### 高级:自定义指纹 + 代理
|
|
131
|
+
|
|
132
|
+
```python
|
|
133
|
+
await call_tool("browser_launch", {
|
|
134
|
+
"headless": True,
|
|
135
|
+
"humanize": True,
|
|
136
|
+
"proxy": "socks5://user:pass@proxy:1080",
|
|
137
|
+
"fingerprint_seed": "my-unique-seed-123",
|
|
138
|
+
"geoip": True,
|
|
139
|
+
"locale": "zh-CN",
|
|
140
|
+
})
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### 保存/恢复登录会话
|
|
144
|
+
|
|
145
|
+
```python
|
|
146
|
+
# 登录后保存会话
|
|
147
|
+
await call_tool("browser_save_storage_state", {"path": "session.json"})
|
|
148
|
+
|
|
149
|
+
# 下次使用时恢复会话
|
|
150
|
+
await call_tool("browser_load_storage_state", {"path": "session.json"})
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## 🏗️ 架构
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
MCP 客户端 (Hermes / Claude / Cursor 等)
|
|
157
|
+
│ stdio (JSON-RPC)
|
|
158
|
+
▼
|
|
159
|
+
cloakbrowser-mcp 服务器
|
|
160
|
+
│
|
|
161
|
+
▼
|
|
162
|
+
CloakBrowser (Playwright 兼容 API)
|
|
163
|
+
│
|
|
164
|
+
▼
|
|
165
|
+
隐身 Chromium (57 个 C++ 源码补丁)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
服务器维护一个浏览器单例。所有工具操作当前活跃页面。首次调用工具时会自动启动浏览器(无需手动 launch)。
|
|
169
|
+
|
|
170
|
+
## 🔧 与 Hermes Agent 内置浏览器工具的区别
|
|
171
|
+
|
|
172
|
+
| 特性 | Hermes 内置 browser_* | CloakBrowser MCP |
|
|
173
|
+
|------|----------------------|------------------|
|
|
174
|
+
| 反 bot 检测 | ❌ 原生 Playwright,容易被检测 | ✅ 57 个 C++ 补丁,通过全部检测 |
|
|
175
|
+
| navigator.webdriver | true(可被检测) | false(完全隐藏) |
|
|
176
|
+
| TLS 指纹 | Playwright 默认 | 真实 Chrome |
|
|
177
|
+
| 人机模拟 | ❌ 无 | ✅ 贝塞尔曲线鼠标 + 逐字符输入 |
|
|
178
|
+
| 代理 + GeoIP | ❌ 不支持 | ✅ HTTP/SOCKS5 + 地理定位 |
|
|
179
|
+
| 指纹种子 | ❌ 固定 | ✅ 每次随机或自定义 |
|
|
180
|
+
| 会话持久化 | ❌ 不支持 | ✅ 保存/加载 cookies |
|
|
181
|
+
|
|
182
|
+
## 📁 项目结构
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
cloakbrowser-mcp/
|
|
186
|
+
├── src/
|
|
187
|
+
│ └── cloakbrowser_mcp/
|
|
188
|
+
│ ├── __init__.py # 版本信息
|
|
189
|
+
│ ├── server.py # MCP 服务器入口(工具注册)
|
|
190
|
+
│ ├── tools.py # 22 个工具的实现
|
|
191
|
+
│ └── browser_manager.py # 浏览器生命周期管理(单例)
|
|
192
|
+
├── examples/
|
|
193
|
+
│ └── hermes_config.yaml # Hermes Agent 配置示例
|
|
194
|
+
├── skills/
|
|
195
|
+
│ └── cloakbrowser-mcp/
|
|
196
|
+
│ └── SKILL.md # 配套 Hermes Skill 文件
|
|
197
|
+
├── pyproject.toml # 打包配置
|
|
198
|
+
├── README.md # 英文文档
|
|
199
|
+
├── README_CN.md # 中文文档(本文件)
|
|
200
|
+
└── LICENSE # MIT 许可证
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
## 🛠️ 开发
|
|
204
|
+
|
|
205
|
+
```bash
|
|
206
|
+
git clone https://github.com/MiwooMiwoo/cloakbrowser-mcp.git
|
|
207
|
+
cd cloakbrowser-mcp
|
|
208
|
+
pip install -e ".[dev]"
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## 📄 许可证
|
|
212
|
+
|
|
213
|
+
MIT
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Example: Hermes Agent configuration for CloakBrowser MCP Server
|
|
2
|
+
# Add this to ~/.hermes/config.yaml
|
|
3
|
+
|
|
4
|
+
mcp_servers:
|
|
5
|
+
cloakbrowser:
|
|
6
|
+
command: "python"
|
|
7
|
+
args: ["-m", "cloakbrowser_mcp.server"]
|
|
8
|
+
timeout: 120 # per-tool-call timeout in seconds
|
|
9
|
+
connect_timeout: 60 # initial connection timeout
|
|
10
|
+
|
|
11
|
+
# After adding this config, restart Hermes Agent.
|
|
12
|
+
# Tools will be registered as mcp_cloakbrowser_browser_*
|
|
13
|
+
#
|
|
14
|
+
# Example tool names:
|
|
15
|
+
# mcp_cloakbrowser_browser_launch
|
|
16
|
+
# mcp_cloakbrowser_browser_navigate
|
|
17
|
+
# mcp_cloakbrowser_browser_snapshot
|
|
18
|
+
# mcp_cloakbrowser_browser_click
|
|
19
|
+
# mcp_cloakbrowser_browser_type
|
|
20
|
+
# mcp_cloakbrowser_browser_screenshot
|
|
21
|
+
# ...
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "mcp-cloakbrowser"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "MCP server for CloakBrowser - stealth browser automation via Model Context Protocol"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = { text = "MIT" }
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
authors = [{ name = "MiwooMiwoo" }]
|
|
13
|
+
keywords = ["mcp", "cloakbrowser", "browser", "automation", "stealth", "anti-detect"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.10",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
24
|
+
"Topic :: Internet :: WWW/HTTP :: Browsers",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
dependencies = [
|
|
28
|
+
"cloakbrowser>=0.3.0",
|
|
29
|
+
"mcp>=1.0.0",
|
|
30
|
+
]
|
|
31
|
+
|
|
32
|
+
[project.scripts]
|
|
33
|
+
cloakbrowser-mcp = "cloakbrowser_mcp.server:run"
|
|
34
|
+
|
|
35
|
+
[project.urls]
|
|
36
|
+
Homepage = "https://github.com/MiwooMiwoo/cloakbrowser-mcp"
|
|
37
|
+
Repository = "https://github.com/MiwooMiwoo/cloakbrowser-mcp"
|
|
38
|
+
Issues = "https://github.com/MiwooMiwoo/cloakbrowser-mcp/issues"
|
|
39
|
+
|
|
40
|
+
[tool.hatch.build.targets.wheel]
|
|
41
|
+
packages = ["src/cloakbrowser_mcp"]
|