agent-stealth-browser 0.1.0

通用的 AI 浏览器自动化 MCP 工具，让 AI Agent 能够以 Stealth 模式操作任意网站，兼容 agent-browser 接口

Agent Stealth Browser

🕵️ 通用的 AI 浏览器自动化 MCP 工具，让 AI Agent 能够以 Stealth 模式 智能地操作任意网站。

Agent Stealth Browser 是 agent-browser 的 Stealth 增强版本，提供完全兼容的 API 接口，但具备绕过反爬检测的能力。

✨ 特性

• 🔄 完全兼容 agent-browser API - 无缝替换，相同的工具名和参数格式
• 🕵️ Stealth 模式 - 绕过 Cloudflare、reCAPTCHA 等反爬检测
• 🌍 跨平台支持 - Windows、macOS、Linux 自动适配
• 🍪 Cookie 持久化 - 保存登录状态，跨会话使用
• 📸 截图能力 - 支持全页面或指定元素截图
• 🎯 @ref 元素定位 - 与 agent-browser 一致的元素引用格式

📦 安装

方式 1: uvx (推荐)

uvx agent-stealth-browser

方式 2: pip

pip install agent-stealth-browser

# 安装 Playwright 浏览器
playwright install chromium

# 可选: 安装 stealth 增强
pip install playwright-stealth

方式 3: npx

npx agent-stealth-browser

🔧 MCP 配置

Claude Desktop / Cursor

在 MCP 配置文件中添加:

{
  "mcpServers": {
    "stealth-browser": {
      "command": "uvx",
      "args": ["agent-stealth-browser"]
    }
  }
}

或使用 npx:

{
  "mcpServers": {
    "stealth-browser": {
      "command": "npx",
      "args": ["agent-stealth-browser"]
    }
  }
}

🛠️ 可用工具

工具名	描述	对应 agent-browser 命令
browser_navigate	导航到指定 URL	open <url>
browser_snapshot	获取页面交互元素快照	snapshot -i
browser_click	点击元素	click @e1
browser_fill	填写输入框（先清空）	fill @e1 "text"
browser_type	逐字输入（模拟真人）	type @e1 "text"
browser_press	按下键盘按键	press Enter
browser_scroll	滚动页面	scroll down 500
browser_hover	悬停在元素上	hover @e1
browser_select	选择下拉框选项	select @e1 "value"
browser_get	获取元素/页面信息	get text @e1
browser_eval	执行 JavaScript	eval "code"
browser_screenshot	页面截图	screenshot
browser_wait	等待时间或元素	wait
browser_cookies_save	保存 cookies	-
browser_cookies_load	加载 cookies	-
browser_close	关闭浏览器	close

📝 使用示例

基础浏览

1. browser_navigate: {"url": "https://example.com"}
2. browser_snapshot: {}
3. browser_click: {"target": "@e1"}

表单填写

1. browser_navigate: {"url": "https://example.com/login"}
2. browser_snapshot: {}
3. browser_fill: {"target": "@e3", "text": "username"}
4. browser_fill: {"target": "@e4", "text": "password"}
5. browser_click: {"target": "@e5"}

保持登录状态

# 登录后保存 cookies
browser_cookies_save: {"domain": "example"}

# 下次启动时加载
browser_navigate: {"url": "https://example.com"}
browser_cookies_load: {"domain": "example"}
browser_navigate: {"url": "https://example.com"}  # 刷新页面应用 cookies

🌍 跨平台支持

Agent Stealth Browser 自动检测运行平台并适配：

平台	User-Agent	浏览器参数
macOS	Macintosh; Intel Mac OS X	标准参数
macOS (Apple Silicon)	Macintosh; Apple M1	标准参数
Windows	Windows NT 10.0; Win64	--disable-gpu
Linux	X11; Linux x86_64	--no-sandbox 等

🔒 Stealth 模式

默认启用以下反检测措施：

• ✅ 隐藏 navigator.webdriver 属性
• ✅ 模拟真实 Chrome 环境
• ✅ 隐藏自动化特征
• ✅ 支持 playwright-stealth 插件（可选增强）

增强 Stealth 模式

安装 playwright-stealth 获得更强的反检测能力：

pip install playwright-stealth

📁 数据存储

• Cookies: ~/.agent_stealth_browser/cookies/

🔄 与 agent-browser 的区别

特性	agent-browser	agent-stealth-browser
Stealth 模式	❌	✅
反爬绕过	❌	✅
Cookie 持久化	❌	✅
跨平台适配	✅	✅
API 兼容性	-	100% 兼容

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT License - 详见 LICENSE 文件