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.
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *$py.class
4
+ *.egg-info/
5
+ dist/
6
+ build/
7
+ .eggs/
8
+ *.egg
9
+ .venv/
10
+ venv/
11
+ .env
12
+ *.log
13
+ .DS_Store
14
+ Thumbs.db
@@ -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"]