Browser Use

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

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

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:

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

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

# Learning mode - discover and save a skill
Go to GitHub trending page and extract the top 5 repositories
learn: true
save_skill_as: github_trending

# Using a learned skill
task: Get trending Python repositories
skill_name: github_trending
skill_params: {"language": "python", "limit": 10}

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:

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

# With search limit
Research the security implications of CDP-based browser automation
max_searches: 10

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

Skill Management Tools

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_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_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

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
  }
}

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:

# List recent tasks
limit: 10

# List only running tasks
status_filter: running
limit: 5

# List failed tasks
status_filter: failed

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_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

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

# Step 1: Deep research
run_deep_research
topic: What are the best practices for MCP server development in 2025?
max_searches: 8

# Step 2: Follow-up investigation
run_browser_agent
task: Go to the top-ranked article and extract code examples

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

Learning and Reusing Skills

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

# Step 1: Learn a 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

# Step 2: List learned skills
skill_list

# Step 3: Reuse the skill (faster direct execution)
run_browser_agent
task: Get current top stories from Hacker News
skill_name: hackernews_top_stories
skill_params: {"limit": 5}

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

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

# Step 2: Check progress
task_list
status_filter: running

# Step 3: Get details
task_get
task_id: a1b2c3d4

# Step 4: Cancel if needed
task_cancel
task_id: a1b2c3d4

Advanced Features

Skill-Based Execution

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.

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)

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
```

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/)

Troubleshooting

Server Not Responding

# Check server health
health_check

# Check if server is running
# In terminal: mcp-server-browser-use status

Task Stuck or Failing

# 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>

Skill Execution Fails

# Get skill details to verify parameters
skill_get
skill_name: my_skill

# Try without skill to re-learn
run_browser_agent
task: <original task>
learn: true
save_skill_as: my_skill_v2

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

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

browser-use

NPX Install

Tags

SKILL.md Content

Browser Use

When to Use

Core Tools

run_browser_agent

run_deep_research

Skill Management Tools

skill_list

skill_get

skill_delete

Task Management Tools

health_check

task_list

task_get

task_cancel

Common Workflows

Web Research Workflow

Form Automation Workflow

Learning and Reusing Skills

Long-Running Task Management

Advanced Features

Skill-Based Execution

Progress Tracking

Background Task Support

Configuration

Troubleshooting

Server Not Responding

Task Stuck or Failing

Skill Execution Fails

Best Practices

Limitations