# Install the plugin
/plugin install browser-use/mcp-browser-use

# Set API key (environment variable - recommended)
export GEMINI_API_KEY=your-key-here

# Or use config file
mcp-server-browser-use config set -k llm.api_key -v your-key-here

# Clone and install
git clone https://github.com/Saik0s/mcp-browser-use.git
cd mcp-server-browser-use
uv sync

# Install browser
uv run playwright install chromium

# Start the server
uv run mcp-server-browser-use server

{
  "mcpServers": {
    "browser-use": {
      "type": "streamable-http",
      "url": "http://localhost:8383/mcp"
    }
  }
}

{
  "mcpServers": {
    "browser-use": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8383/mcp"]
    }
  }
}

mcp-server-browser-use config view

mcp-server-browser-use config set -k llm.provider -v openai
mcp-server-browser-use config set -k llm.model_name -v gpt-4o
# Note: Set API keys via environment variables (e.g., ANTHROPIC_API_KEY) for better security
# mcp-server-browser-use config set -k llm.api_key -v sk-...
mcp-server-browser-use config set -k browser.headless -v false
mcp-server-browser-use config set -k agent.max_steps -v 30

Environment Variables > Config File > Defaults

# Set user data directory
mcp-server-browser-use config set -k browser.user_data_dir -v ~/.chrome-browser-use

# Launch Chrome with debugging enabled
google-chrome --remote-debugging-port=9222

# Configure CDP connection (localhost only for security)
mcp-server-browser-use config set -k browser.cdp_url -v http://localhost:9222

mcp-server-browser-use server          # Start as background daemon
mcp-server-browser-use server -f       # Start in foreground (for debugging)
mcp-server-browser-use status          # Check if running
mcp-server-browser-use stop            # Stop the daemon
mcp-server-browser-use logs -f         # Tail server logs

mcp-server-browser-use tools           # List all available MCP tools
mcp-server-browser-use call run_browser_agent task="Go to google.com"
mcp-server-browser-use call run_deep_research topic="quantum computing"

mcp-server-browser-use config view     # Show all settings
mcp-server-browser-use config set -k <key> -v <value>
mcp-server-browser-use config path     # Show config file location

mcp-server-browser-use tasks           # List recent tasks
mcp-server-browser-use tasks --status running
mcp-server-browser-use task <id>       # Get task details
mcp-server-browser-use task cancel <id> # Cancel a running task
mcp-server-browser-use health          # Server health + stats

mcp-server-browser-use call skill_list
mcp-server-browser-use call skill_get name="my-skill"
mcp-server-browser-use call skill_delete name="my-skill"

mcp-server-browser-use call run_browser_agent \
  task="Find the price of iPhone 16 Pro on Apple's website"

mcp-server-browser-use call run_deep_research \
  topic="Latest developments in quantum computing" \
  max_searches=5

┌─────────────────────────────────────────────────────────┐
│  Phase 1: PLANNING                                       │
│  LLM generates 3-5 focused search queries from topic     │
└─────────────────────────────┬───────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────┐
│  Phase 2: SEARCHING                                      │
│  For each query:                                         │
│    • Browser agent executes search                       │
│    • Extracts URL + summary from results                 │
│    • Stores findings                                     │
└─────────────────────────────┬───────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────┐
│  Phase 3: SYNTHESIS                                      │
│  LLM creates markdown report:                            │
│    1. Executive Summary                                  │
│    2. Key Findings (by theme)                            │
│    3. Analysis and Insights                              │
│    4. Gaps and Limitations                               │
│    5. Conclusion with Sources                            │
└─────────────────────────────────────────────────────────┘

PENDING ──► RUNNING ──► COMPLETED
               │
               ├──► FAILED
               └──► CANCELLED

INITIALIZING → PLANNING → NAVIGATING → EXTRACTING → SYNTHESIZING

mcp-server-browser-use tasks

┌──────────────┬───────────────────┬───────────┬──────────┬──────────┐
│ ID           │ Tool              │ Status    │ Progress │ Duration │
├──────────────┼───────────────────┼───────────┼──────────┼──────────┤
│ a1b2c3d4     │ run_browser_agent │ completed │ 15/15    │ 45s      │
│ e5f6g7h8     │ run_deep_research │ running   │ 3/7      │ 2m 15s   │
└──────────────┴───────────────────┴───────────┴──────────┴──────────┘

mcp-server-browser-use task a1b2c3d4

mcp-server-browser-use health

mcp-server-browser-use config set -k skills.enabled -v true

Without Skills:  Browser navigation → 60-120 seconds
With Skills:     Direct API call    → 1-3 seconds

mcp-server-browser-use call run_browser_agent \
  task="Find React packages on npmjs.com" \
  learn=true \
  save_skill_as="npm-search"

mcp-server-browser-use call run_browser_agent \
  skill_name="npm-search" \
  skill_params='{"query": "vue"}'

Initialize CDP session
    ↓
Navigate to domain (establish cookies)
    ↓
Execute fetch() via Runtime.evaluate
    ↓
Parse response with JSONPath
    ↓
Return data

Inject navigation hints into task prompt
    ↓
Agent uses hints as guidance
    ↓
Agent discovers and calls API
    ↓
Return data

name: npm-search
description: Search for packages on npmjs.com
version: "1.0"

# For direct execution (fast path)
request:
  url: "https://www.npmjs.com/search?q={query}"
  method: GET
  headers:
    Accept: application/json
  response_type: json
  extract_path: "objects[*].package"

# For hint-based execution (fallback)
hints:
  navigation:
    - step: "Go to npmjs.com"
      url: "https://www.npmjs.com"
  money_request:
    url_pattern: "/search"
    method: GET

# Auth recovery (if API returns 401/403)
auth_recovery:
  trigger_on_status: [401, 403]
  recovery_page: "https://www.npmjs.com/login"

# Usage stats
success_count: 12
failure_count: 1
last_used: "2024-01-15T10:30:00Z"

request:
  url: "https://api.example.com/search?q={query}&limit={limit}"
  body_template: '{"filters": {"category": "{category}"}}'

auth_recovery:
  trigger_on_status: [401, 403]
  recovery_page: "https://example.com/login"
  max_retries: 2

http://localhost:8383

curl http://localhost:8383/api/health

{
  "status": "healthy",
  "uptime_seconds": 1234.5,
  "memory_mb": 256.7,
  "running_tasks": 2,
  "tasks": [...],
  "stats": {...}
}

# List all tasks
curl http://localhost:8383/api/tasks

# Filter by status
curl http://localhost:8383/api/tasks?status=running

# Limit results
curl http://localhost:8383/api/tasks?limit=50

curl http://localhost:8383/api/tasks/abc123

const events = new EventSource('/api/tasks/abc123/logs');
events.onmessage = (e) => console.log(JSON.parse(e.data));

curl http://localhost:8383/api/skills

{
  "skills": [
    {
      "name": "npm-search",
      "description": "Search for packages on npmjs.com",
      "success_rate": 92.5,
      "usage_count": 15,
      "last_used": "2024-01-15T10:30:00Z"
    }
  ],
  "count": 1,
  "skills_directory": "/Users/you/.config/browser-skills"
}

curl http://localhost:8383/api/skills/npm-search

curl -X DELETE http://localhost:8383/api/skills/npm-search

curl -X POST http://localhost:8383/api/skills/npm-search/run \
  -H "Content-Type: application/json" \
  -d '{"params": {"query": "react"}}'

{
  "task_id": "abc123...",
  "skill_name": "npm-search",
  "message": "Skill execution started",
  "status_url": "/api/tasks/abc123..."
}

curl -X POST http://localhost:8383/api/learn \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Search for TypeScript packages on npmjs.com",
    "skill_name": "npm-search"
  }'

{
  "task_id": "def456...",
  "learning_task": "Search for TypeScript packages on npmjs.com",
  "skill_name": "npm-search",
  "message": "Learning session started",
  "status_url": "/api/tasks/def456..."
}

const events = new EventSource('/api/events');
events.onmessage = (e) => {
  const data = JSON.parse(e.data);
  console.log(`Task ${data.task_id}: ${data.status}`);
};

{
  "task_id": "abc123",
  "full_task_id": "abc123-full-uuid...",
  "tool": "run_browser_agent",
  "status": "running",
  "stage": "navigating",
  "progress": {
    "current": 5,
    "total": 15,
    "percent": 33.3,
    "message": "Loading page..."
  }
}

┌─────────────────────────────────────────────────────────────────────────┐
│                           MCP CLIENTS                                    │
│              (Claude Desktop, mcp-remote, CLI call)                      │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │ HTTP POST /mcp
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         FastMCP SERVER                                   │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      MCP TOOLS                                    │   │
│  │  • run_browser_agent    • skill_list/get/delete                  │   │
│  │  • run_deep_research    • health_check/task_list/task_get        │   │
│  └──────────────────────────────────────────────────────────────────┘   │
└────────┬──────────────┬─────────────────┬────────────────┬──────────────┘
         │              │                 │                │
         ▼              ▼                 ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐
│   CONFIG    │  │  PROVIDERS  │  │   SKILLS    │  │    OBSERVABILITY    │
│  Pydantic   │  │ 12 LLMs     │  │  Learn+Run  │  │   Task Tracking     │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────────────┘
                                         │
                                         ▼
                              ┌─────────────────────────┐
                              │      browser-use        │
                              │   (Agent + Playwright)  │
                              └─────────────────────────┘

src/mcp_server_browser_use/
├── server.py            # FastMCP server + MCP tools
├── cli.py               # Typer CLI for daemon management
├── config.py            # Pydantic settings
├── providers.py         # LLM factory (12 providers)
│
├── observability/       # Task tracking
│   ├── models.py        # TaskRecord, TaskStatus, TaskStage
│   ├── store.py         # SQLite persistence
│   └── logging.py       # Structured logging
│
├── skills/              # Machine-learned browser skills
│   ├── models.py        # Skill, SkillRequest, AuthRecovery
│   ├── store.py         # YAML persistence
│   ├── recorder.py      # CDP network capture
│   ├── analyzer.py      # LLM skill extraction
│   ├── runner.py        # Direct fetch() execution
│   └── executor.py      # Hint injection
│
└── research/            # Deep research workflow
    ├── models.py        # SearchResult, ResearchSource
    └── machine.py       # Plan → Search → Synthesize