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:

code

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

code

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

code

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:

code

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:

code

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

code

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:

code

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

code

# 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

code

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

code

# 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

code

# 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

code

# Check server health
health_check

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

Task Stuck or Failing

code

# 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

code

# 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