Content
# mcp-server-browser-use
MCP server that gives AI assistants the power to control a web browser.
[](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 <key> -v <value>
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 <id> # Get task details
mcp-server-browser-use task cancel <id> # 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
