MCP浏览器操作器

一个用于浏览器自动化的模型控制协议 (MCP) 服务器，它使 LLM 能够通过标准化的 JSON-RPC 接口控制 Web 浏览器、与网页交互以及分析 Web 内容。

特性

• 浏览器管理: 创建、导航、操作和关闭浏览器实例
• 任务管理: 使用任务 ID 跟踪浏览器操作的状态
• Web 交互: 使用 OpenAI 的 Computer Use API 执行自然语言指令
• 浏览器工具: 访问控制台日志、网络活动、屏幕截图等
• 审计: 运行可访问性、性能、SEO 和其他网页审计

要求

• Python 3.11+
• Playwright
• OpenAI API 密钥 (用于 Computer Use API)

安装

1. 克隆此存储库:

   git clone https://github.com/yourusername/operator-mcp.git
   cd operator-mcp
   

2. 安装依赖项:

   pip install -e .
   

3. 安装 Playwright 浏览器:

   playwright install chromium
   

4. 设置您的 OpenAI API 密钥:

   export OPENAI_API_KEY=your-api-key
   

使用

启动 MCP 服务器:

./run-server

服务器监听 stdin 上的 JSON-RPC 请求，并在 stdout 上响应，遵循 MCP 协议。

可执行脚本

• run-server - 运行 MCP 服务器 (主入口点)

  # 运行 MCP 服务器
  ./run-server
  
  # 使用特定日志目录运行
  ./run-server --log-dir /path/to/logs
  
  # 在调试模式下运行
  ./run-server --debug
  

• run-tests - 运行所有测试 (可以选择仅运行单元测试或集成测试)

  # 运行所有测试
  ./run-tests
  
  # 仅运行单元测试 (更快)
  ./run-tests --unit-only
  
  # 仅运行集成测试
  ./run-tests --integration-only
  
  # 使用详细输出运行
  ./run-tests --verbose
  
  # 运行特定测试
  ./run-tests --test TestBrowserOperatorMethods
  

• run-test-harness - 运行带有 MCP Inspector 的服务器以进行交互式测试

  # 运行带有 MCP Inspector 的服务器以进行交互式测试
  ./run-test-harness
  

核心方法

浏览器管理

• 创建浏览器: 初始化一个新的浏览器实例

  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "mcp__browser-operator__create-browser",
    "params": {
      "project_name": "my-project"
    }
  }
  

• 导航浏览器: 将浏览器定向到指定的 URL

  {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "mcp__browser-operator__navigate-browser",
    "params": {
      "project_name": "my-project",
      "url": "https://example.com"
    }
  }
  

• 操作浏览器: 执行自然语言指令以进行浏览器交互

  {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "mcp__browser-operator__operate-browser",
    "params": {
      "project_name": "my-project",
      "instruction": "找到此页面上的标题，并告诉我它说了什么。"
    }
  }
  

• 关闭浏览器: 终止浏览器实例

  {
    "jsonrpc": "2.0",
    "id": 4,
    "method": "mcp__browser-operator__close-browser",
    "params": {
      "project_name": "my-project"
    }
  }
  

任务管理

• 获取任务状态: 按任务 ID 检索操作的状态和结果

  {
    "jsonrpc": "2.0",
    "id": 5,
    "method": "mcp__browser-operator__get-job-status",
    "params": {
      "job_id": "job-12345"
    }
  }
  

• 列出任务: 查看最近的浏览器操作任务

  {
    "jsonrpc": "2.0",
    "id": 6,
    "method": "mcp__browser-operator__list-jobs",
    "params": {
      "limit": 10
    }
  }
  

用户笔记

• 添加笔记: 创建和存储与浏览器操作相关的笔记

  {
    "jsonrpc": "2.0",
    "id": 7,
    "method": "mcp__browser-operator__add-note",
    "params": {
      "name": "My Note",
      "content": "关于此浏览器会话的重要信息"
    }
  }
  

附加方法

浏览器调试工具

• 获取控制台日志: mcp__browser-tools__getConsoleLogs
• 获取控制台错误: mcp__browser-tools__getConsoleErrors
• 获取网络日志: mcp__browser-tools__getNetworkLogs
• 获取网络错误: mcp__browser-tools__getNetworkErrors
• 截取屏幕截图: mcp__browser-tools__takeScreenshot
• 获取选定的元素: mcp__browser-tools__getSelectedElement
• 清除日志: mcp__browser-tools__wipeLogs

审计工具

• 运行可访问性审计: mcp__browser-tools__runAccessibilityAudit
• 运行性能审计: mcp__browser-tools__runPerformanceAudit
• 运行 SEO 审计: mcp__browser-tools__runSEOAudit
• 运行 NextJS 审计: mcp__browser-tools__runNextJSAudit
• 运行最佳实践审计: mcp__browser-tools__runBestPracticesAudit
• 运行调试器模式: mcp__browser-tools__runDebuggerMode
• 运行审计模式: mcp__browser-tools__runAuditMode

异步工作流模式

浏览器操作是异步的，并使用基于任务的方法：

1. 启动操作: 调用一个浏览器方法，该方法返回一个 job_id
2. 轮询完成: 使用 get-job-status 直到任务完成
3. 处理结果: 任务完成后，从任务状态访问结果

这种方法可以防止客户端超时，同时允许复杂的浏览器操作完成。

持久浏览器状态

当使用项目名称创建浏览器时，MCP 操作器会维护持久状态：

• 浏览器状态（cookies、本地存储、会话存储）在会话之间保留
• 多个项目可以维护独立的浏览器状态
• 适用于维护登录会话、购物车或其他个性化状态

项目结构

• src/mcp_operator/: 主包
  • __init__.py: 包初始化
  • __main__.py: 包的入口点
  • server.py: MCP 服务器实现
  • browser.py: 浏览器操作器实现
  • cua/: Computer Use API 组件
    • agent.py: Agent 实现
    • computer.py: Computer 接口
    • utils.py: 实用函数
• run-server: 运行 MCP 服务器的脚本
• run-tests: 运行单元测试和集成测试的脚本
• run-test-harness: 运行带有 MCP Inspector 的脚本

开发

使用 MCP Inspector

对于调试，请使用 MCP Inspector:

# 使用包含的 run-test-harness 脚本
./run-test-harness

# 或者直接:
npx @modelcontextprotocol/inspector ./run-server

这提供了一个 Web 界面来测试您的 MCP 服务器。

安全

• 阻止潜在有害站点的域名
• 导航前的 URL 验证
• 不同浏览器实例之间的会话隔离
• 基于文件的日志记录（没有 stdout 来保留 MCP 协议）