# mcp-server-browser-use MCP server that gives AI assistants the power to control a web browser. [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE) --- ## Table of Contents - [What is this?](#what-is-this) - [Installation](#installation) - [Web UI](#web-ui) - [Web Dashboard](#web-dashboard) - [Configuration](#configuration) - [CLI Reference](#cli-reference) - [MCP Tools](#mcp-tools) - [Deep Research](#deep-research) - [Observability](#observability) - [Skills System](#skills-system-super-alpha) - [REST API Reference](#rest-api-reference) - [Architecture](#architecture) - [License](#license) --- ## What is this? This wraps [browser-use](https://github.com/browser-use/browser-use) as an MCP server, letting Claude (or any MCP client) automate a real browser—navigate pages, fill forms, click buttons, extract data, and more. ### Why HTTP instead of stdio? Browser automation tasks take 30-120+ seconds. The standard MCP stdio transport has timeout issues with long-running operations—connections drop mid-task. **HTTP transport solves this** by running as a persistent daemon that handles requests reliably regardless of duration. --- ## Installation ### Claude Code Plugin (Recommended) Install as a Claude Code plugin for automatic setup: ```bash # Install the plugin /plugin install browser-use/mcp-browser-use ``` The plugin automatically: - Installs Playwright browsers on first run - Starts the HTTP daemon when Claude Code starts - Registers the MCP server with Claude **Set your API key** (the browser agent needs an LLM to decide actions): ```bash # 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 ``` That's it! Claude can now use browser automation tools. ### Manual Installation For other MCP clients or standalone use: ```bash # 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 ``` **Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "browser-use": { "type": "streamable-http", "url": "http://localhost:8383/mcp" } } } ``` For MCP clients that don't support HTTP transport, use `mcp-remote` as a proxy: ```json { "mcpServers": { "browser-use": { "command": "npx", "args": ["mcp-remote", "http://localhost:8383/mcp"] } } } ``` --- ## Web UI Access the task viewer at http://localhost:8383 when the daemon is running. **Features:** - Real-time task list with status and progress - Task details with execution logs - Server health status and uptime - Running tasks monitoring The web UI provides visibility into browser automation tasks without requiring CLI commands. --- ## Web Dashboard Access the full-featured dashboard at http://localhost:8383/dashboard when the daemon is running. **Features:** - **Tasks Tab:** Complete task history with filtering, real-time status updates, and detailed execution logs - **Skills Tab:** Browse, inspect, and manage learned skills with usage statistics - **History Tab:** Historical view of all completed tasks with filtering by status and time **Key Capabilities:** - Run existing skills directly from the dashboard with custom parameters - Start learning sessions to capture new skills - Delete outdated or invalid skills - Monitor running tasks with live progress updates - View full task results and error details The dashboard provides a comprehensive web interface for managing all aspects of browser automation without CLI commands. --- ## Configuration Settings are stored in `~/.config/mcp-server-browser-use/config.json`. **View current config:** ```bash mcp-server-browser-use config view ``` **Change settings:** ```bash 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 ``` ### Settings Reference | Key | Default | Description | |-----|---------|-------------| | `llm.provider` | `google` | LLM provider (anthropic, openai, google, azure_openai, groq, deepseek, cerebras, ollama, bedrock, browser_use, openrouter, vercel) | | `llm.model_name` | `gemini-3-flash-preview` | Model for the browser agent | | `llm.api_key` | - | API key for the provider (prefer env vars: GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.) | | `browser.headless` | `true` | Run browser without GUI | | `browser.cdp_url` | - | Connect to existing Chrome (e.g., http://localhost:9222) | | `browser.user_data_dir` | - | Chrome profile directory for persistent logins/cookies | | `browser.chromium_sandbox` | `true` | Enable Chromium sandboxing for security | | `agent.max_steps` | `20` | Max steps per browser task | | `agent.use_vision` | `true` | Enable vision capabilities for the agent | | `research.max_searches` | `5` | Max searches per research task | | `research.search_timeout` | - | Timeout for individual searches | | `server.host` | `127.0.0.1` | Server bind address | | `server.port` | `8383` | Server port | | `server.results_dir` | - | Directory to save results | | `server.auth_token` | - | Auth token for non-localhost connections | | `skills.enabled` | `false` | Enable skills system (beta - disabled by default) | | `skills.directory` | `~/.config/browser-skills` | Skills storage location | | `skills.validate_results` | `true` | Validate skill execution results | ### Config Priority ``` Environment Variables > Config File > Defaults ``` Environment variables use prefix `MCP_` + section + `_` + key (e.g., `MCP_LLM_PROVIDER`). ### Using Your Own Browser **Option 1: Persistent Profile (Recommended)** Use a dedicated Chrome profile to preserve logins and cookies: ```bash # Set user data directory mcp-server-browser-use config set -k browser.user_data_dir -v ~/.chrome-browser-use ``` **Option 2: Connect to Existing Chrome** Connect to an existing Chrome instance (useful for advanced debugging): ```bash # 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 ``` --- ## CLI Reference ### Server Management ```bash 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 ``` ### Calling Tools ```bash 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" ``` ### Configuration ```bash mcp-server-browser-use config view # Show all settings mcp-server-browser-use config set -k -v mcp-server-browser-use config path # Show config file location ``` ### Observability ```bash mcp-server-browser-use tasks # List recent tasks mcp-server-browser-use tasks --status running mcp-server-browser-use task # Get task details mcp-server-browser-use task cancel # Cancel a running task mcp-server-browser-use health # Server health + stats ``` ### Skills Management ```bash 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" ``` **Tip:** Skills can also be managed through the web dashboard at http://localhost:8383/dashboard for a visual interface with one-click execution and learning sessions. --- ## MCP Tools These tools are exposed via MCP for AI clients: | Tool | Description | Typical Duration | |------|-------------|------------------| | `run_browser_agent` | Execute browser automation tasks | 60-120s | | `run_deep_research` | Multi-search research with synthesis | 2-5 min | | `skill_list` | List learned skills | <1s | | `skill_get` | Get skill definition | <1s | | `skill_delete` | Delete a skill | <1s | | `health_check` | Server status and running tasks | <1s | | `task_list` | Query task history | <1s | | `task_get` | Get full task details | <1s | ### run_browser_agent The main tool. Tell it what you want in plain English: ```bash mcp-server-browser-use call run_browser_agent \ task="Find the price of iPhone 16 Pro on Apple's website" ``` The agent launches a browser, navigates to apple.com, finds the product, and returns the price. **Parameters:** | Parameter | Type | Description | |-----------|------|-------------| | `task` | string | What to do (required) | | `max_steps` | int | Override default max steps | | `skill_name` | string | Use a learned skill | | `skill_params` | JSON | Parameters for the skill | | `learn` | bool | Enable learning mode | | `save_skill_as` | string | Name for the learned skill | ### run_deep_research Multi-step web research with automatic synthesis: ```bash mcp-server-browser-use call run_deep_research \ topic="Latest developments in quantum computing" \ max_searches=5 ``` The agent searches multiple sources, extracts key findings, and compiles a markdown report. --- ## Deep Research Deep research executes a 3-phase workflow: ``` ┌─────────────────────────────────────────────────────────┐ │ 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 │ └─────────────────────────────────────────────────────────┘ ``` Reports can be auto-saved by configuring `research.save_directory`. --- ## Observability All tool executions are tracked in SQLite for debugging and monitoring. ### Task Lifecycle ``` PENDING ──► RUNNING ──► COMPLETED │ ├──► FAILED └──► CANCELLED ``` ### Task Stages During execution, tasks progress through granular stages: ``` INITIALIZING → PLANNING → NAVIGATING → EXTRACTING → SYNTHESIZING ``` ### Querying Tasks **List recent tasks:** ```bash 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 │ └──────────────┴───────────────────┴───────────┴──────────┴──────────┘ ``` **Get task details:** ```bash mcp-server-browser-use task a1b2c3d4 ``` **Server health:** ```bash mcp-server-browser-use health ``` Shows uptime, memory usage, and currently running tasks. ### MCP Tools for Observability AI clients can query task status directly: - `health_check` - Server status + list of running tasks - `task_list` - Recent tasks with optional status filter - `task_get` - Full details of a specific task ### Storage - **Database:** `~/.config/mcp-server-browser-use/tasks.db` - **Retention:** Completed tasks auto-deleted after 7 days - **Format:** SQLite with WAL mode for concurrency --- ## Skills System (Super Alpha) > **Warning:** This feature is experimental and under active development. Expect rough edges. **Skills are disabled by default.** Enable them first: ```bash mcp-server-browser-use config set -k skills.enabled -v true ``` Skills let you "teach" the agent a task once, then replay it **50x faster** by reusing discovered API endpoints instead of full browser automation. ### The Problem Browser automation is slow (60-120 seconds per task). But most websites have APIs behind their UI. If we can discover those APIs, we can call them directly. ### The Solution Skills capture the API calls made during a browser session and replay them directly via CDP (Chrome DevTools Protocol). ``` Without Skills: Browser navigation → 60-120 seconds With Skills: Direct API call → 1-3 seconds ``` ### Learning a Skill ```bash mcp-server-browser-use call run_browser_agent \ task="Find React packages on npmjs.com" \ learn=true \ save_skill_as="npm-search" ``` What happens: 1. **Recording:** CDP captures all network traffic during execution 2. **Analysis:** LLM identifies the "money request"—the API call that returns the data 3. **Extraction:** URL patterns, headers, and response parsing rules are saved 4. **Storage:** Skill saved as YAML to `~/.config/browser-skills/npm-search.yaml` ### Using a Skill ```bash mcp-server-browser-use call run_browser_agent \ skill_name="npm-search" \ skill_params='{"query": "vue"}' ``` ### Two Execution Modes Every skill supports two execution paths: #### 1. Direct Execution (Fast Path) ~2 seconds If the skill captured an API endpoint (`SkillRequest`): ``` Initialize CDP session ↓ Navigate to domain (establish cookies) ↓ Execute fetch() via Runtime.evaluate ↓ Parse response with JSONPath ↓ Return data ``` #### 2. Hint-Based Execution (Fallback) ~60-120 seconds If direct execution fails or no API was found: ``` Inject navigation hints into task prompt ↓ Agent uses hints as guidance ↓ Agent discovers and calls API ↓ Return data ``` ### Skill File Format Skills are stored as YAML in `~/.config/browser-skills/`: ```yaml 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" ``` ### Parameters Skills support parameterized URLs and request bodies: ```yaml request: url: "https://api.example.com/search?q={query}&limit={limit}" body_template: '{"filters": {"category": "{category}"}}' ``` Parameters are substituted at execution time from `skill_params`. ### Auth Recovery If an API returns 401/403, skills can trigger auth recovery: ```yaml auth_recovery: trigger_on_status: [401, 403] recovery_page: "https://example.com/login" max_retries: 2 ``` The system will navigate to the recovery page (letting you log in) and retry. ### Limitations - **API Discovery:** Only works if the site has an API. Sites that render everything server-side won't yield useful skills. - **Auth State:** Skills rely on browser cookies. If you're logged out, they may fail. - **API Changes:** If a site changes their API, the skill breaks. Falls back to hint-based execution. - **Complex Flows:** Multi-step workflows (login → navigate → search) may not capture cleanly. --- ## REST API Reference The server exposes REST endpoints for direct HTTP access. All endpoints return JSON unless otherwise specified. ### Base URL ``` http://localhost:8383 ``` ### Health & Status **GET /api/health** Server health check with running task information. ```bash curl http://localhost:8383/api/health ``` Response: ```json { "status": "healthy", "uptime_seconds": 1234.5, "memory_mb": 256.7, "running_tasks": 2, "tasks": [...], "stats": {...} } ``` ### Tasks **GET /api/tasks** List recent tasks with optional filtering. ```bash # 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 ``` **GET /api/tasks/{task_id}** Get full details of a specific task. ```bash curl http://localhost:8383/api/tasks/abc123 ``` **GET /api/tasks/{task_id}/logs** (SSE) Real-time task progress stream via Server-Sent Events. ```javascript const events = new EventSource('/api/tasks/abc123/logs'); events.onmessage = (e) => console.log(JSON.parse(e.data)); ``` ### Skills **GET /api/skills** List all available skills. ```bash curl http://localhost:8383/api/skills ``` Response: ```json { "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" } ``` **GET /api/skills/{name}** Get full skill definition as JSON. ```bash curl http://localhost:8383/api/skills/npm-search ``` **DELETE /api/skills/{name}** Delete a skill. ```bash curl -X DELETE http://localhost:8383/api/skills/npm-search ``` **POST /api/skills/{name}/run** Execute a skill with parameters (starts background task). ```bash curl -X POST http://localhost:8383/api/skills/npm-search/run \ -H "Content-Type: application/json" \ -d '{"params": {"query": "react"}}' ``` Response: ```json { "task_id": "abc123...", "skill_name": "npm-search", "message": "Skill execution started", "status_url": "/api/tasks/abc123..." } ``` **POST /api/learn** Start a learning session to capture a new skill (starts background task). ```bash 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" }' ``` Response: ```json { "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..." } ``` ### Real-Time Updates **GET /api/events** (SSE) Server-Sent Events stream for all task updates. ```javascript const events = new EventSource('/api/events'); events.onmessage = (e) => { const data = JSON.parse(e.data); console.log(`Task ${data.task_id}: ${data.status}`); }; ``` Event format: ```json { "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..." } } ``` --- ## Architecture ### High-Level Overview ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 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) │ └─────────────────────────┘ ``` ### Module Structure ``` 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 ``` ### File Locations | What | Where | |------|-------| | Config | `~/.config/mcp-server-browser-use/config.json` | | Tasks DB | `~/.config/mcp-server-browser-use/tasks.db` | | Skills | `~/.config/browser-skills/*.yaml` | | Server Log | `~/.local/state/mcp-server-browser-use/server.log` | | Server PID | `~/.local/state/mcp-server-browser-use/server.json` | ### Supported LLM Providers - OpenAI - Anthropic - Google Gemini - Azure OpenAI - Groq - DeepSeek - Cerebras - Ollama (local) - AWS Bedrock - OpenRouter - Vercel AI --- ## License MIT

Mcp Browser Use

Install

Mcp Browser Use

Install