MCP Browser Co Gnome

noVNC浏览器自动化套件

一个全面的浏览器自动化套件，在Docker中运行带有noVNC可视化的Playwright，提供用于控制的Python API，记录用于调试的所有浏览器操作/状态，启用会话持久性和回放，并集成用于远程访问的Cloudflare快速隧道。

特性

• 可视化浏览器访问：通过noVNC web界面查看浏览器并与之交互
• 剧作家自动化：完整的剧作家API，具有用于反探测的隐形模式
• 会话保持：保存和恢复浏览器状态（Cookie、本地存储、URL）
• 综合录音：视频、剧作家痕迹、HAR文件和动作日志
• 远程访问：Cloudflare用于共享浏览器访问的快速隧道
• 基于Docker：环境一致，易于部署

快速开始

1.启动Docker服务

# Start browser and video recording
docker compose up -d

# Or with remote access tunnel
docker compose --profile tunnel up -d

2.访问noVNC

打开http://localhost:6080在您的浏览器中。默认密码： secret

3.安装Python包

pip install -e .

4.运行自动化

import asyncio
from novnc_automation import AutomationBrowser

async def main():
    # Connect to the Docker browser via CDP
    async with AutomationBrowser(
        session_id="my-session",
        cdp_endpoint="http://localhost:9222"
    ) as browser:
        await browser.goto("https://example.com")
        await browser.click("a")
        await browser.screenshot("result")

asyncio.run(main())

或者使用Docker编排器进行编程控制：

from novnc_automation.docker import quick_start, quick_stop

# Start Docker containers with tunnel
status = quick_start(with_tunnel=True)
print(f"Tunnel URL: {status.tunnel_url}")
print(f"noVNC URL: {status.novnc_url}")

# ... run automation ...

quick_stop()

建筑

+-------------------+     +-------------------+     +-------------------+
|  Python Client    |---->|  Browser Container|---->|  Video Recorder   |
|  (Host machine)   |     |  (Playwright+VNC) |     |  (FFmpeg)         |
+-------------------+     +-------------------+     +-------------------+
                                  |
                                  v
                          +-------------------+
                          |  Cloudflared      |---> trycloudflare.com
                          |  (Quick Tunnel)   |     (Public URL)
                          +-------------------+

api参考

自动化浏览器

浏览器自动化的主要类。

from novnc_automation import AutomationBrowser

# Basic usage
async with AutomationBrowser(session_id="my-session") as browser:
    await browser.goto("https://example.com")
    await browser.click("#button")
    await browser.fill("#input", "text")
    await browser.screenshot("screenshot_name")

# Restore a previous session
async with AutomationBrowser() as browser:
    await browser.start(restore_session="my-session")
    # Browser state (cookies, localStorage) restored

导航方法

• goto(url, wait_until="load") -导航到URL
• reload() -重新加载页面
• go_back() -回到历史
• go_forward() -在历史中前进

交互方法

• click(selector) -点击元素
• fill(selector, value) -填写输入字段
• type(selector, text, delay=0) -带按键模拟的类型
• press(selector, key) -按键盘键
• select_option(selector, value) -选择下拉选项
• check(selector) / uncheck(selector) -切换复选框
• hover(selector) -将鼠标悬停在元素上

等待方法

• wait_for_selector(selector, state="visible") -等待元素
• wait_for_load_state(state="load") -等待页面加载
• wait_for_url(url_pattern) -等待URL匹配

内容提取

• get_text(selector) -获取元素文本
• get_attribute(selector, name) -获取属性值
• get_inner_html(selector) -获取内部HTML
• evaluate(js_expression) -运行JavaScript

会话管理器

管理浏览器会话持久性。

from novnc_automation import SessionManager

manager = SessionManager()

# List all sessions
sessions = await manager.list_sessions()

# Load session state
state = await manager.load_session_state("my-session")

# Delete session
await manager.delete_session("my-session")

隧道经理

为远程访问创建Cloudflare快速隧道。

from novnc_automation import TunnelManager

# As context manager
async with TunnelManager() as tunnel:
    print(f"Remote URL: {tunnel.url}")
    # Keep running...

# Manual control
tunnel = TunnelManager()
url = await tunnel.start()
print(f"Remote URL: {url}")
# ...
await tunnel.stop()

# Get URL from Docker container
url = TunnelManager.get_tunnel_url_from_docker_logs()

短暂数据

所有临时数据都保存到 tmp/ 目录（gitignored）：

用户输入捕获

用户交互在两个级别上自动捕获：

JS级别 -通过注入脚本执行DOM事件：

{
  "source": "user",
  "level": "js",
  "action": "click",
  "x": 450,
  "y": 320,
  "element": {"tag": "button", "id": "login", "text": "Sign In"}
}

X11级别 -带有屏幕截图的原始输入：

{
  "source": "user",
  "level": "x11",
  "action": "mouse_click",
  "pixel_x": 450,
  "pixel_y": 320,
  "normalized_x": 0.234375,
  "normalized_y": 0.296296,
  "screenshot": "tmp/x11_screenshots/20260204_123456_click_450_320.png"
}

查看痕迹

# Open Playwright trace viewer
npx playwright show-trace tmp/traces/my-session.zip

配置

环境变量

YAML配置

创建 config.yml:

browser:
  headless: false
  stealth_mode: true
  viewport_width: 1920
  viewport_height: 1080

recording:
  record_video: true
  record_trace: true
  record_har: true
  tmp_dir: tmp
  sessions_dir: sessions

tunnel:
  enable_tunnel: false
  tunnel_port: 6080

docker:
  vnc_password: secret
  resolution: 1920x1080x24

Docker服务

浏览器容器

• 端口6080：noVNC web界面
• 端口5900：VNC协议
• 端口9222：Chrome DevTools协议

视频录制

使用Selenium的FFmpeg容器进行屏幕录制。

Cloudflare隧道

远程访问的可选服务。启用：

docker compose --profile tunnel up -d

例子

请参阅 examples/ 目录：

• basic_usage.py -简单的自动化示例
• session_persistence.py -保存和恢复会话
• remote_access.py -Cloudflare隧道使用情况

MCP服务器

该软件包包括一个MCP（模型上下文协议）服务器，允许LLM控制浏览器。

安装

pip install -e .

配置

添加到您的Claude桌面配置(~/.config/claude/claude_desktop_config.json 在Linux或 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "novnc-automation": {
      "command": "novnc-mcp",
      "env": {
        "HEADLESS": "false",
        "STEALTH_MODE": "true"
      }
    }
  }
}

或者使用紫外线：

{
  "mcpServers": {
    "novnc-automation": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/novnc_automation_record", "novnc-mcp"]
    }
  }
}

可用工具

Docker管理

浏览器控件

OmniParser（UI元素检测）

会话和日志

用于UI元素检测的OmniParser

MCP服务器集成 OmniParser v2 （Microsoft）用于检测和理解UI元素：

• 你只活一次 用于图标/按钮检测
• 光学字符识别 用于文本提取
• 佛罗伦萨-2 用于元素字幕

# Basic install uses HuggingFace Spaces API (no GPU needed)
pip install -e .

# For local inference (requires GPU)
pip install -e '.[omniparser-local]'

工作流程示例：

1. omniparser_analyze -检测所有UI元素
2. 查看带注释的图像（带编号的边界框）
3. omniparser_click 使用元素ID进行交互
4. 或使用 omniparser_get_html 检查元素HTML

输出文件保存到 tmp/omniparser/:

• YYYYMMDD_HHMMSS_annotated.png -带有编号bbox的图像
• YYYYMMDD_HHMMSS_elements.json -元素详细信息（id、框、类型、文本、描述）

注： 未来的VLM查询工具计划通过本地视觉语言模型用于任意UI问题。目前，Claude Code可以直接分析带注释的图像。

使用GUI Actor进行自然语言点击

MCP服务器集成 GUI演员，一种能够理解自然语言指令以找到点击目标的视觉语言模型。

# Install GUI-Actor dependencies
pip install -e '.[gui-actor]'

通过MCP使用示例：

User: Click the login button
LLM: [calls natural_language_click with instruction="Click the login button"]

该模型截取屏幕截图，用人工智能进行分析，然后点击预测的位置。

临时文件

MCP服务器将文件保存到 tmp/ 目录（gitignored）：

屏幕截图文件名遵循以下模式： YYYYMMDD_HHMMSS_fff_flattened_url.png

隐身模式

自动化使用 playwright-stealth 通过这些反检测措施：

• navigator.webdriver 着手 undefined
• 真实的浏览器插件和语言
• 从用户代理中删除“HeadlessChrome”
• WebGL供应商/渲染器欺骗
• Chrome运行时补丁

发展

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/

许可证

麻省理工学院