browser-use

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Browser Use

浏览器自动化工具使用

AI-powered browser automation for web interactions, research, and data extraction powered by the browser-use library.

由browser-use库提供支持的、基于AI的浏览器自动化工具，用于网页交互、调研和数据提取。

When to Use

适用场景

Automate web interactions (fill forms, click buttons, navigate pages)
Perform deep research across multiple web sources
Extract structured data from web pages
Learn and replay browser workflows as reusable skills
Monitor and manage long-running browser automation tasks

自动化网页交互（填写表单、点击按钮、页面导航）
跨多个网页来源执行深度调研
从网页中提取结构化数据
学习并可重放浏览器工作流作为可复用Skill
监控和管理长时间运行的浏览器自动化任务

Core Tools

核心工具

run_browser_agent

Execute a browser automation task using AI. Supports skill-based execution, learning mode, and background task execution.

Parameters:

```
task
```
(string, required) - Natural language description of what to do in the browser
```
max_steps
```
(integer, optional) - Maximum number of agent steps (default: from settings)
```
skill_name
```
(string, optional) - Name of a learned skill to use for hints
```
skill_params
```
(string or dict, optional) - Parameters for the skill (JSON string or dict)
```
learn
```
(boolean, optional) - Enable learning mode to discover and extract APIs
```
save_skill_as
```
(string, optional) - Name to save learned skill (requires learn=True)

Returns: Result of the browser automation task. In learning mode, includes skill extraction status.

Examples:

undefined

使用AI执行浏览器自动化任务。支持基于Skill的执行、学习模式和后台任务执行。

参数：

```
task
```
（字符串，必填）- 对浏览器操作内容的自然语言描述
```
max_steps
```
（整数，可选）- Agent的最大步骤数（默认值：来自设置）
```
skill_name
```
（字符串，可选）- 用于提供提示的已学习Skill名称
```
skill_params
```
（字符串或字典，可选）- Skill的参数（JSON字符串或字典）
```
learn
```
（布尔值，可选）- 启用学习模式以发现和提取API
```
save_skill_as
```
（字符串，可选）- 保存已学习Skill的名称（需要设置learn=True）

返回值： 浏览器自动化任务的结果。在学习模式下，包含Skill提取状态。

示例：

undefined

Basic usage

基础用法

Search for "Claude Code plugins" on Google and summarize the top 3 results

在Google上搜索“Claude Code plugins”并总结前3条结果

With max steps

设置最大步骤数

Fill out the contact form at https://example.com/contact with my information max_steps: 20

在https://example.com/contact填写联系表单，填入我的信息 max_steps: 20

Learning mode - discover and save a skill

学习模式 - 发现并保存Skill

Go to GitHub trending page and extract the top 5 repositories learn: true save_skill_as: github_trending

访问GitHub趋势页面并提取前5个仓库 learn: true save_skill_as: github_trending

Using a learned skill

使用已学习的Skill

task: Get trending Python repositories skill_name: github_trending skill_params: {"language": "python", "limit": 10}

undefined

task: 获取趋势Python仓库 skill_name: github_trending skill_params: {"language": "python", "limit": 10}

undefined

run_deep_research

Perform multi-source research on a topic with AI-guided search and synthesis.

Parameters:

```
topic
```
(string, required) - The research topic or question to investigate
```
max_searches
```
(integer, optional) - Maximum number of web searches (default: from settings)
```
save_to_file
```
(string, optional) - Optional file path to save the research report

Returns: A comprehensive research report in markdown format

Examples:

undefined

通过AI引导的搜索和综合，对某个主题执行多来源调研。

参数：

```
topic
```
（字符串，必填）- 要调研的主题或问题
```
max_searches
```
（整数，可选）- 最大网页搜索次数（默认值：来自设置）
```
save_to_file
```
（字符串，可选）- 保存调研报告的可选文件路径

返回值： 一份Markdown格式的综合调研报告

示例：

undefined

Basic research

基础调研

What are the latest developments in AI-powered browser automation?

AI驱动浏览器自动化的最新发展有哪些？

With search limit

设置搜索次数上限

Research the security implications of CDP-based browser automation max_searches: 10

调研基于CDP的浏览器自动化的安全影响 max_searches: 10

Save to file

保存到文件

Compare Playwright, Puppeteer, and Selenium for 2025 save_to_file: /path/to/research/browser-automation-comparison.md

undefined

对比2025年的Playwright、Puppeteer和Selenium save_to_file: /path/to/research/browser-automation-comparison.md

undefined

Skill Management Tools

Skill管理工具

skill_list

List all available learned browser skills with usage statistics.

Parameters: None

Returns: JSON list of skill summaries with name, description, success rate, usage count, and last used timestamp

Example:

json

{
  "skills": [
    {
      "name": "github_trending",
      "description": "Extract trending repositories from GitHub",
      "success_rate": 95.0,
      "usage_count": 20,
      "last_used": "2025-12-20T18:00:00"
    }
  ],
  "skills_directory": "/Users/user/.config/browser-skills"
}

列出所有可用的已学习浏览器Skill及使用统计数据。

参数： 无

返回值： 包含Skill摘要的JSON列表，内容包括名称、描述、成功率、使用次数和最后使用时间戳

示例：

json

{
  "skills": [
    {
      "name": "github_trending",
      "description": "Extract trending repositories from GitHub",
      "success_rate": 95.0,
      "usage_count": 20,
      "last_used": "2025-12-20T18:00:00"
    }
  ],
  "skills_directory": "/Users/user/.config/browser-skills"
}

skill_get

Get full details of a specific skill including API endpoints, parameters, and execution hints.

Parameters:

```
skill_name
```
(string, required) - Name of the skill to retrieve

Returns: Full skill definition in YAML format

Example:

skill_name: github_trending

获取特定Skill的完整详情，包括API端点、参数和执行提示。

参数：

```
skill_name
```
（字符串，必填）- 要获取的Skill名称

返回值： YAML格式的完整Skill定义

示例：

skill_name: github_trending

skill_delete

Delete a learned skill by name.

Parameters:

```
skill_name
```
(string, required) - Name of the skill to delete

Returns: Success or error message

Example:

skill_name: outdated_skill

按名称删除已学习的Skill。

参数：

```
skill_name
```
（字符串，必填）- 要删除的Skill名称

返回值： 成功或错误消息

示例：

skill_name: outdated_skill

Task Management Tools

任务管理工具

health_check

Check if the browser automation server is running and get system statistics.

Parameters: None

Returns: JSON with server health status, uptime, memory usage, and running tasks

Example Response:

json

{
  "status": "healthy",
  "uptime_seconds": 3600.5,
  "memory_mb": 256.3,
  "running_tasks": 2,
  "tasks": [
    {
      "task_id": "a1b2c3d4",
      "tool": "run_browser_agent",
      "stage": "navigating",
      "progress": "5/100",
      "message": "Searching Google..."
    }
  ],
  "stats": {
    "total_completed": 45,
    "total_failed": 2,
    "avg_duration_sec": 32.1
  }
}

检查浏览器自动化服务器是否运行，并获取系统统计数据。

参数： 无

返回值： 包含服务器健康状态、运行时间、内存使用情况和运行中任务的JSON

示例响应：

json

{
  "status": "healthy",
  "uptime_seconds": 3600.5,
  "memory_mb": 256.3,
  "running_tasks": 2,
  "tasks": [
    {
      "task_id": "a1b2c3d4",
      "tool": "run_browser_agent",
      "stage": "navigating",
      "progress": "5/100",
      "message": "Searching Google..."
    }
  ],
  "stats": {
    "total_completed": 45,
    "total_failed": 2,
    "avg_duration_sec": 32.1
  }
}

task_list

List recent browser automation and research tasks with filtering.

Parameters:

```
limit
```
(integer, optional) - Maximum number of tasks to return (default: 20)
```
status_filter
```
(string, optional) - Filter by status: "running", "completed", "failed", "pending"

Returns: JSON list of recent tasks

Example:

undefined

列出近期的浏览器自动化和调研任务，并支持筛选。

参数：

```
limit
```
（整数，可选）- 返回的最大任务数（默认值：20）
```
status_filter
```
（字符串，可选）- 按状态筛选："running"、"completed"、"failed"、"pending"

返回值： 近期任务的JSON列表

示例：

undefined

List recent tasks

列出近期任务

limit: 10

List only running tasks

仅列出运行中的任务

status_filter: running limit: 5

List failed tasks

列出失败的任务

status_filter: failed

undefined

status_filter: failed

undefined

task_get

Get detailed information about a specific task including input, output, and progress.

Parameters:

```
task_id
```
(string, required) - Task ID (full UUID or prefix match)

Returns: JSON with complete task details, timestamps, and result/error

Example:

task_id: a1b2c3d4

获取特定任务的详细信息，包括输入、输出和进度。

参数：

```
task_id
```
（字符串，必填）- 任务ID（完整UUID或前缀匹配）

返回值： 包含完整任务详情、时间戳和结果/错误的JSON

示例：

task_id: a1b2c3d4

task_cancel

Cancel a running browser agent or research task.

Parameters:

```
task_id
```
(string, required) - Task ID (full UUID or prefix match)

Returns: JSON with success status and message

Example:

task_id: a1b2c3d4

取消运行中的浏览器Agent或调研任务。

参数：

```
task_id
```
（字符串，必填）- 任务ID（完整UUID或前缀匹配）

返回值： 包含成功状态和消息的JSON

示例：

task_id: a1b2c3d4

Common Workflows

常见工作流

Web Research Workflow

网页调研工作流

Use
```
run_deep_research
```
with your research question
Review the synthesized markdown report
Use
```
run_browser_agent
```
for follow-up exploration of specific sources
Check
```
task_list
```
to monitor progress

undefined

使用
```
run_deep_research
```
传入你的调研问题
查看生成的Markdown格式综合报告
使用
```
run_browser_agent
```
对特定来源进行后续探索
查看
```
task_list
```
以监控进度

undefined

Step 1: Deep research

步骤1：深度调研

run_deep_research topic: What are the best practices for MCP server development in 2025? max_searches: 8

run_deep_research topic: 2025年MCP服务器开发的最佳实践有哪些？ max_searches: 8

Step 2: Follow-up investigation

步骤2：后续调查

run_browser_agent task: Go to the top-ranked article and extract code examples

undefined

run_browser_agent task: 访问排名第一的文章并提取代码示例

undefined

Form Automation Workflow

表单自动化工作流

Use
```
run_browser_agent
```
with task describing the form
Include URL if known, or let agent search for it
Agent navigates, fills fields, and submits
Use
```
task_get
```
to verify completion

run_browser_agent
task: Fill out the contact form at https://example.com/contact with name "John Doe", email "john@example.com", and message "Request for demo"
max_steps: 30

使用
```
run_browser_agent
```
传入描述表单的任务
如果已知URL则包含，否则让Agent自行搜索
Agent会导航到页面、填写字段并提交
使用
```
task_get
```
验证完成情况

run_browser_agent
task: 在https://example.com/contact填写联系表单，姓名为"John Doe"，邮箱为"john@example.com"，消息为"请求演示"
max_steps: 30

Learning and Reusing Skills

学习并复用Skill

Run
```
run_browser_agent
```
with
```
learn: true
```
to discover APIs
Agent records network calls and extracts patterns
Save skill with
```
save_skill_as
```
Use
```
skill_list
```
to see learned skills
Reuse with
```
skill_name
```
parameter for faster execution

undefined

运行
```
run_browser_agent
```
并设置
```
learn: true
```
以发现API
Agent会记录网络调用并提取模式
使用
```
save_skill_as
```
保存Skill
使用
```
skill_list
```
查看已学习的Skill
使用
```
skill_name
```
参数复用Skill以加快执行速度

undefined

Step 1: Learn a skill

步骤1：学习Skill

run_browser_agent task: Go to Hacker News and extract the top 10 stories with titles, URLs, and scores learn: true save_skill_as: hackernews_top_stories

run_browser_agent task: 访问Hacker News并提取前10条故事的标题、URL和评分 learn: true save_skill_as: hackernews_top_stories

Step 2: List learned skills

步骤2：列出已学习的Skill

skill_list

Step 3: Reuse the skill (faster direct execution)

步骤3：复用Skill（更快的直接执行）

run_browser_agent task: Get current top stories from Hacker News skill_name: hackernews_top_stories skill_params: {"limit": 5}

undefined

run_browser_agent task: 获取Hacker News当前的热门故事 skill_name: hackernews_top_stories skill_params: {"limit": 5}

undefined

Long-Running Task Management

长时间运行任务管理

Start a browser automation task (runs in background)
Use
```
task_list
```
to check status
Use
```
task_get
```
for detailed progress
Use
```
task_cancel
```
if needed

undefined

启动浏览器自动化任务（在后台运行）
使用
```
task_list
```
查看状态
使用
```
task_get
```
获取详细进度
如有需要使用
```
task_cancel
```
取消任务

undefined

Step 1: Start task

步骤1：启动任务

run_browser_agent task: Research all articles on example.com blog and create a summary max_steps: 200

run_browser_agent task: 调研example.com博客上的所有文章并生成摘要 max_steps: 200

Step 2: Check progress

步骤2：检查进度

task_list status_filter: running

Step 3: Get details

步骤3：获取详情

task_get task_id: a1b2c3d4

Step 4: Cancel if needed

步骤4：如有需要取消任务

task_cancel task_id: a1b2c3d4

undefined

task_cancel task_id: a1b2c3d4

undefined

Advanced Features

高级功能

Skill-Based Execution

基于Skill的执行

When a skill is learned with API endpoints, it supports direct execution which bypasses the AI agent for much faster performance:

First run: Agent explores the website (60-120 seconds)
Skill learned: API patterns extracted and saved
Subsequent runs: Direct API calls (2-5 seconds)

Fallback behavior: If direct execution fails (auth required, API changed), automatically falls back to agent-based execution.

当Skill通过API端点学习完成后，它支持直接执行，绕过AI Agent以大幅提升性能：

首次运行：Agent探索网站（60-120秒）
Skill学习完成：提取并保存API模式
后续运行：直接调用API（2-5秒）

回退行为： 如果直接执行失败（需要授权、API变更），会自动回退到基于Agent的执行模式。

Progress Tracking

进度跟踪

Both

run_browser_agent

and

run_deep_research

support real-time progress tracking:

Step-by-step navigation updates
Progress percentage (current step / total steps)
Current stage (initializing, navigating, extracting, analyzing)
Task message (current action description)

run_browser_agent

和

run_deep_research

都支持实时进度跟踪：

分步导航更新
进度百分比（当前步骤/总步骤）
当前阶段（初始化、导航、提取、分析）
任务消息（当前操作描述）

Background Task Support

后台任务支持

Long-running tasks automatically run in background when requested by the MCP client:

Tasks tracked in SQLite database
Persistent across server restarts
Query status anytime with
```
task_list
```
and
```
task_get
```
Cancel with
```
task_cancel
```

当MCP客户端请求时，长时间运行的任务会自动在后台运行：

任务在SQLite数据库中跟踪
服务器重启后仍可保留
可随时使用
```
task_list
```
和
```
task_get
```
查询状态
可使用
```
task_cancel
```
取消任务

Configuration

配置

The browser-use MCP server can be configured via

~/.config/mcp-server-browser-use/config.json

or environment variables. Key settings:

```
browser.headless
```
- Run browser in headless mode (default: true)
```
browser.cdp_url
```
- Connect to external Chrome via CDP (optional)
```
agent.max_steps
```
- Default maximum steps (default: 100)
```
research.max_searches
```
- Default research searches (default: 5)
```
skills.enabled
```
- Enable skill learning and execution (default: true)
```
skills.directory
```
- Where to store learned skills (default: ~/.config/browser-skills/)

browser-use MCP服务器可通过

~/.config/mcp-server-browser-use/config.json

或环境变量进行配置。关键设置：

```
browser.headless
```
- 以无头模式运行浏览器（默认值：true）
```
browser.cdp_url
```
- 通过CDP连接到外部Chrome（可选）
```
agent.max_steps
```
- 默认最大步骤数（默认值：100）
```
research.max_searches
```
- 默认调研搜索次数（默认值：5）
```
skills.enabled
```
- 启用Skill学习和执行（默认值：true）
```
skills.directory
```
- 已学习Skill的存储位置（默认值：~/.config/browser-skills/）

Troubleshooting

故障排除

Server Not Responding

服务器无响应

undefined

undefined

Check server health

检查服务器健康状态

health_check

Check if server is running

检查服务器是否运行

In terminal: mcp-server-browser-use status

在终端中执行：mcp-server-browser-use status

undefined

undefined

Task Stuck or Failing

任务卡住或失败

undefined

undefined

List running tasks

列出运行中的任务

task_list status_filter: running

Get task details

获取任务详情

task_get task_id: <task_id>

Cancel if stuck

如果卡住则取消任务

task_cancel task_id: <task_id>

undefined

task_cancel task_id: <task_id>

undefined

Skill Execution Fails

Skill执行失败

undefined

undefined

Get skill details to verify parameters

获取Skill详情以验证参数

skill_get skill_name: my_skill

Try without skill to re-learn

尝试不使用Skill重新学习

run_browser_agent task: <original task> learn: true save_skill_as: my_skill_v2

undefined

run_browser_agent task: <原始任务> learn: true save_skill_as: my_skill_v2

undefined

Best Practices

最佳实践

Start with health_check - Verify server is ready before running tasks
Use descriptive task names - Help the AI understand your intent clearly
Set reasonable max_steps - 30-50 for simple tasks, 100-200 for complex research
Learn frequently-used workflows - Save time with skill-based execution
Monitor long tasks - Use task_list and task_get to track progress
Clean up failed tasks - Use task_cancel to free resources
Save research to files - Use save_to_file to preserve research reports

先执行health_check - 运行任务前验证服务器是否就绪
使用描述性任务名称 - 帮助AI清晰理解你的意图
设置合理的max_steps - 简单任务设置30-50，复杂调研设置100-200
学习常用工作流 - 使用基于Skill的执行节省时间
监控长时间任务 - 使用task_list和task_get跟踪进度
清理失败任务 - 使用task_cancel释放资源
将调研结果保存到文件 - 使用save_to_file保留调研报告

Limitations

局限性

Browser automation requires the MCP server to be running as a daemon
CDP-based browsers must be on localhost (security restriction)
Some websites may block automation (respect robots.txt and rate limits)
Skill learning requires successful task completion and API discovery
Task cancellation may take a few seconds to complete gracefully

浏览器自动化要求MCP服务器作为守护进程运行
基于CDP的浏览器必须在本地主机上（安全限制）
部分网站可能会阻止自动化操作（请遵守robots.txt和速率限制）
Skill学习需要任务成功完成且能发现API
任务取消可能需要几秒时间才能优雅完成