browser-use

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:

{
  "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:

{
  "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

1. Use run_deep_research with your research question
2. Review the synthesized markdown report
3. Use run_browser_agent for follow-up exploration of specific sources
4. 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

1. Use run_browser_agent with task describing the form
2. Include URL if known, or let agent search for it
3. Agent navigates, fills fields, and submits
4. 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

1. Run run_browser_agent with learn: true to discover APIs
2. Agent records network calls and extracts patterns
3. Save skill with save_skill_as
4. Use skill_list to see learned skills
5. 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

1. Start a browser automation task (runs in background)
2. Use task_list to check status
3. Use task_get for detailed progress
4. 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

1. Start with health_check - Verify server is ready before running tasks
2. Use descriptive task names - Help the AI understand your intent clearly
3. Set reasonable max_steps - 30-50 for simple tasks, 100-200 for complex research
4. Learn frequently-used workflows - Save time with skill-based execution
5. Monitor long tasks - Use task_list and task_get to track progress
6. Clean up failed tasks - Use task_cancel to free resources
7. 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