Skip to content
Back to search

browser-use

MarketplaceWorks with Claude CodeGitHub

MCP server that gives AI assistants the power to control a web browser.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/saik0s--mcp-browser-use/badge.svg)](/listings/saik0s--mcp-browser-use)

HTML

<a href="/listings/saik0s--mcp-browser-use"><img src="/api/listings/saik0s--mcp-browser-use/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code Plugin (Recommended)

Install as a Claude Code plugin for automatic setup:

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

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

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

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

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "browser-use",
  3. "owner": {
  4. "name": "Igor Tarasenko"
  5. },
  6. "metadata": {
  7. "description": "Browser automation plugins",
  8. "version": "1.0.0",
  9. "pluginRoot": ".."
  10. },
  11. "plugins": [
  12. {
  13. "name": "mcp-browser-use",
  14. "source": "..",
  15. "description": "Browser automation via MCP - AI-driven web interactions with Playwright",
  16. "version": "1.0.0",
  17. "keywords": ["browser", "automation", "mcp", "playwright"],
  18. "category": "automation"
  19. }
  20. ]
  21. }
README.md · README · 852 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-server-browser-use
  2. MCP server that gives AI assistants the power to control a web browser.
  3. [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)
  4. ---
  5. ## Table of Contents
  6. - [What is this?](#what-is-this)
  7. - [Installation](#installation)
  8. - [Web UI](#web-ui)
  9. - [Web Dashboard](#web-dashboard)
  10. - [Configuration](#configuration)
  11. - [CLI Reference](#cli-reference)
  12. - [MCP Tools](#mcp-tools)
  13. - [Deep Research](#deep-research)
  14. - [Observability](#observability)
  15. - [Skills System](#skills-system-super-alpha)
  16. - [REST API Reference](#rest-api-reference)
  17. - [Architecture](#architecture)
  18. - [License](#license)
  19. ---
  20. ## What is this?
  21. 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.
  22. ### Why HTTP instead of stdio?
  23. 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.
  24. ---
  25. ## Installation
  26. ### Claude Code Plugin (Recommended)
  27. Install as a Claude Code plugin for automatic setup:
  28. ```bash
  29. # Install the plugin
  30. /plugin install browser-use/mcp-browser-use
  31. ```
  32. The plugin automatically:
  33. - Installs Playwright browsers on first run
  34. - Starts the HTTP daemon when Claude Code starts
  35. - Registers the MCP server with Claude
  36. **Set your API key** (the browser agent needs an LLM to decide actions):
  37. ```bash
  38. # Set API key (environment variable - recommended)
  39. export GEMINI_API_KEY=your-key-here
  40. # Or use config file
  41. mcp-server-browser-use config set -k llm.api_key -v your-key-here
  42. ```
  43. That's it! Claude can now use browser automation tools.
  44. ### Manual Installation
  45. For other MCP clients or standalone use:
  46. ```bash
  47. # Clone and install
  48. git clone https://github.com/Saik0s/mcp-browser-use.git
  49. cd mcp-server-browser-use
  50. uv sync
  51. # Install browser
  52. uv run playwright install chromium
  53. # Start the server
  54. uv run mcp-server-browser-use server
  55. ```
  56. **Add to Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  57. ```json
  58. {
  59. "mcpServers": {
  60. "browser-use": {
  61. "type": "streamable-http",
  62. "url": "http://localhost:8383/mcp"
  63. }
  64. }
  65. }
  66. ```
  67. For MCP clients that don't support HTTP transport, use `mcp-remote` as a proxy:
  68. ```json
  69. {
  70. "mcpServers": {
  71. "browser-use": {
  72. "command": "npx",
  73. "args": ["mcp-remote", "http://localhost:8383/mcp"]
  74. }
  75. }
  76. }
  77. ```
  78. ---
  79. ## Web UI
  80. Access the task viewer at http://localhost:8383 when the daemon is running.
  81. **Features:**
  82. - Real-time task list with status and progress
  83. - Task details with execution logs
  84. - Server health status and uptime
  85. - Running tasks monitoring
  86. The web UI provides visibility into browser automation tasks without requiring CLI commands.
  87. ---
  88. ## Web Dashboard
  89. Access the full-featured dashboard at http://localhost:8383/dashboard when the daemon is running.
  90. **Features:**
  91. - **Tasks Tab:** Complete task history with filtering, real-time status updates, and detailed execution logs
  92. - **Skills Tab:** Browse, inspect, and manage learned skills with usage statistics
  93. - **History Tab:** Historical view of all completed tasks with filtering by status and time
  94. **Key Capabilities:**
  95. - Run existing skills directly from the dashboard with custom parameters
  96. - Start learning sessions to capture new skills
  97. - Delete outdated or invalid skills
  98. - Monitor running tasks with live progress updates
  99. - View full task results and error details
  100. The dashboard provides a comprehensive web interface for managing all aspects of browser automation without CLI commands.
  101. ---
  102. ## Configuration
  103. Settings are stored in `~/.config/mcp-server-browser-use/config.json`.
  104. **View current config:**
  105. ```bash
  106. mcp-server-browser-use config view
  107. ```
  108. **Change settings:**
  109. ```bash
  110. mcp-server-browser-use config set -k llm.provider -v openai
  111. mcp-server-browser-use config set -k llm.model_name -v gpt-4o
  112. # Note: Set API keys via environment variables (e.g., ANTHROPIC_API_KEY) for better security
  113. # mcp-server-browser-use config set -k llm.api_key -v sk-...
  114. mcp-server-browser-use config set -k browser.headless -v false
  115. mcp-server-browser-use config set -k agent.max_steps -v 30
  116. ```
  117. ### Settings Reference
  118. | Key | Default | Description |
  119. |-----|---------|-------------|
  120. | `llm.provider` | `google` | LLM provider (anthropic, openai, google, azure_openai, groq, deepseek, cerebras, ollama, bedrock, browser_use, openrouter, vercel) |
  121. | `llm.model_name` | `gemini-3-flash-preview` | Model for the browser agent |
  122. | `llm.api_key` | - | API key for the provider (prefer env vars: GEMINI_API_KEY, ANTHROPIC_API_KEY, etc.) |
  123. | `browser.headless` | `true` | Run browser without GUI |
  124. | `browser.cdp_url` | - | Connect to existing Chrome (e.g., http://localhost:9222) |
  125. | `browser.user_data_dir` | - | Chrome profile directory for persistent logins/cookies |
  126. | `browser.chromium_sandbox` | `true` | Enable Chromium sandboxing for security |
  127. | `agent.max_steps` | `20` | Max steps per browser task |
  128. | `agent.use_vision` | `true` | Enable vision capabilities for the agent |
  129. | `research.max_searches` | `5` | Max searches per research task |
  130. | `research.search_timeout` | - | Timeout for individual searches |
  131. | `server.host` | `127.0.0.1` | Server bind address |
  132. | `server.port` | `8383` | Server port |
  133. | `server.results_dir` | - | Directory to save results |
  134. | `server.auth_token` | - | Auth token for non-localhost connections |
  135. | `skills.enabled` | `false` | Enable skills system (beta - disabled by default) |
  136. | `skills.directory` | `~/.config/browser-skills` | Skills storage location |
  137. | `skills.validate_results` | `true` | Validate skill execution results |
  138. ### Config Priority
  139. ```
  140. Environment Variables > Config File > Defaults
  141. ```
  142. Environment variables use prefix `MCP_` + section + `_` + key (e.g., `MCP_LLM_PROVIDER`).
  143. ### Using Your Own Browser
  144. **Option 1: Persistent Profile (Recommended)**
  145. Use a dedicated Chrome profile to preserve logins and cookies:
  146. ```bash
  147. # Set user data directory
  148. mcp-server-browser-use config set -k browser.user_data_dir -v ~/.chrome-browser-use
  149. ```
  150. **Option 2: Connect to Existing Chrome**
  151. Connect to an existing Chrome instance (useful for advanced debugging):
  152. ```bash
  153. # Launch Chrome with debugging enabled
  154. google-chrome --remote-debugging-port=9222
  155. # Configure CDP connection (localhost only for security)
  156. mcp-server-browser-use config set -k browser.cdp_url -v http://localhost:9222
  157. ```
  158. ---
  159. ## CLI Reference
  160. ### Server Management
  161. ```bash
  162. mcp-server-browser-use server # Start as background daemon
  163. mcp-server-browser-use server -f # Start in foreground (for debugging)
  164. mcp-server-browser-use status # Check if running
  165. mcp-server-browser-use stop # Stop the daemon
  166. mcp-server-browser-use logs -f # Tail server logs
  167. ```
  168. ### Calling Tools
  169. ```bash
  170. mcp-server-browser-use tools # List all available MCP tools
  171. mcp-server-browser-use call run_browser_agent task="Go to google.com"
  172. mcp-server-browser-use call run_deep_research topic="quantum computing"
  173. ```
  174. ### Configuration
  175. ```bash
  176. mcp-server-browser-use config view # Show all settings
  177. mcp-server-browser-use config set -k <key> -v <value>
  178. mcp-server-browser-use config path # Show config file location
  179. ```
  180. ### Observability
  181. ```bash
  182. mcp-server-browser-use tasks # List recent tasks
  183. mcp-server-browser-use tasks --status running
  184. mcp-server-browser-use task <id> # Get task details
  185. mcp-server-browser-use task cancel <id> # Cancel a running task
  186. mcp-server-browser-use health # Server health + stats
  187. ```
  188. ### Skills Management
  189. ```bash
  190. mcp-server-browser-use call skill_list
  191. mcp-server-browser-use call skill_get name="my-skill"
  192. mcp-server-browser-use call skill_delete name="my-skill"
  193. ```
  194. **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.
  195. ---
  196. ## MCP Tools
  197. These tools are exposed via MCP for AI clients:
  198. | Tool | Description | Typical Duration |
  199. |------|-------------|------------------|
  200. | `run_browser_agent` | Execute browser automation tasks | 60-120s |
  201. | `run_deep_research` | Multi-search research with synthesis | 2-5 min |
  202. | `skill_list` | List learned skills | <1s |
  203. | `skill_get` | Get skill definition | <1s |
  204. | `skill_delete` | Delete a skill | <1s |
  205. | `health_check` | Server status and running tasks | <1s |
  206. | `task_list` | Query task history | <1s |
  207. | `task_get` | Get full task details | <1s |
  208. ### run_browser_agent
  209. The main tool. Tell it what you want in plain English:
  210. ```bash
  211. mcp-server-browser-use call run_browser_agent \
  212. task="Find the price of iPhone 16 Pro on Apple's website"
  213. ```
  214. The agent launches a browser, navigates to apple.com, finds the product, and returns the price.
  215. **Parameters:**
  216. | Parameter | Type | Description |
  217. |-----------|------|-------------|
  218. | `task` | string | What to do (required) |
  219. | `max_steps` | int | Override default max steps |
  220. | `skill_name` | string | Use a learned skill |
  221. | `skill_params` | JSON | Parameters for the skill |
  222. | `learn` | bool | Enable learning mode |
  223. | `save_skill_as` | string | Name for the learned skill |
  224. ### run_deep_research
  225. Multi-step web research with automatic synthesis:
  226. ```bash
  227. mcp-server-browser-use call run_deep_research \
  228. topic="Latest developments in quantum computing" \
  229. max_searches=5
  230. ```
  231. The agent searches multiple sources, extracts key findings, and compiles a markdown report.
  232. ---
  233. ## Deep Research
  234. Deep research executes a 3-phase workflow:
  235. ```
  236. ┌─────────────────────────────────────────────────────────┐
  237. │ Phase 1: PLANNING │
  238. │ LLM generates 3-5 focused search queries from topic │
  239. └─────────────────────────────┬───────────────────────────┘
  240. ▼
  241. ┌─────────────────────────────────────────────────────────┐
  242. │ Phase 2: SEARCHING │
  243. │ For each query: │
  244. │ • Browser agent executes search │
  245. │ • Extracts URL + summary from results │
  246. │ • Stores findings │
  247. └─────────────────────────────┬───────────────────────────┘
  248. ▼
  249. ┌─────────────────────────────────────────────────────────┐
  250. │ Phase 3: SYNTHESIS │
  251. │ LLM creates markdown report: │
  252. │ 1. Executive Summary │
  253. │ 2. Key Findings (by theme) │
  254. │ 3. Analysis and Insights │
  255. │ 4. Gaps and Limitations │
  256. │ 5. Conclusion with Sources │
  257. └─────────────────────────────────────────────────────────┘
  258. ```
  259. Reports can be auto-saved by configuring `research.save_directory`.
  260. ---
  261. ## Observability
  262. All tool executions are tracked in SQLite for debugging and monitoring.
  263. ### Task Lifecycle
  264. ```
  265. PENDING ──► RUNNING ──► COMPLETED
  266. │
  267. ├──► FAILED
  268. └──► CANCELLED
  269. ```
  270. ### Task Stages
  271. During execution, tasks progress through granular stages:
  272. ```
  273. INITIALIZING → PLANNING → NAVIGATING → EXTRACTING → SYNTHESIZING
  274. ```
  275. ### Querying Tasks
  276. **List recent tasks:**
  277. ```bash
  278. mcp-server-browser-use tasks
  279. ```
  280. ```
  281. ┌──────────────┬───────────────────┬───────────┬──────────┬──────────┐
  282. │ ID │ Tool │ Status │ Progress │ Duration │
  283. ├──────────────┼───────────────────┼───────────┼──────────┼──────────┤
  284. │ a1b2c3d4 │ run_browser_agent │ completed │ 15/15 │ 45s │
  285. │ e5f6g7h8 │ run_deep_research │ running │ 3/7 │ 2m 15s │
  286. └──────────────┴───────────────────┴───────────┴──────────┴──────────┘
  287. ```
  288. **Get task details:**
  289. ```bash
  290. mcp-server-browser-use task a1b2c3d4
  291. ```
  292. **Server health:**
  293. ```bash
  294. mcp-server-browser-use health
  295. ```
  296. Shows uptime, memory usage, and currently running tasks.
  297. ### MCP Tools for Observability
  298. AI clients can query task status directly:
  299. - `health_check` - Server status + list of running tasks
  300. - `task_list` - Recent tasks with optional status filter
  301. - `task_get` - Full details of a specific task
  302. ### Storage
  303. - **Database:** `~/.config/mcp-server-browser-use/tasks.db`
  304. - **Retention:** Completed tasks auto-deleted after 7 days
  305. - **Format:** SQLite with WAL mode for concurrency
  306. ---
  307. ## Skills System (Super Alpha)
  308. > **Warning:** This feature is experimental and under active development. Expect rough edges.
  309. **Skills are disabled by default.** Enable them first:
  310. ```bash
  311. mcp-server-browser-use config set -k skills.enabled -v true
  312. ```
  313. Skills let you "teach" the agent a task once, then replay it **50x faster** by reusing discovered API endpoints instead of full browser automation.
  314. ### The Problem
  315. 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.
  316. ### The Solution
  317. Skills capture the API calls made during a browser session and replay them directly via CDP (Chrome DevTools Protocol).
  318. ```
  319. Without Skills: Browser navigation → 60-120 seconds
  320. With Skills: Direct API call → 1-3 seconds
  321. ```
  322. ### Learning a Skill
  323. ```bash
  324. mcp-server-browser-use call run_browser_agent \
  325. task="Find React packages on npmjs.com" \
  326. learn=true \
  327. save_skill_as="npm-search"
  328. ```
  329. What happens:
  330. 1. **Recording:** CDP captures all network traffic during execution
  331. 2. **Analysis:** LLM identifies the "money request"—the API call that returns the data
  332. 3. **Extraction:** URL patterns, headers, and response parsing rules are saved
  333. 4. **Storage:** Skill saved as YAML to `~/.config/browser-skills/npm-search.yaml`
  334. ### Using a Skill
  335. ```bash
  336. mcp-server-browser-use call run_browser_agent \
  337. skill_name="npm-search" \
  338. skill_params='{"query": "vue"}'
  339. ```
  340. ### Two Execution Modes
  341. Every skill supports two execution paths:
  342. #### 1. Direct Execution (Fast Path) ~2 seconds
  343. If the skill captured an API endpoint (`SkillRequest`):
  344. ```
  345. Initialize CDP session
  346. ↓
  347. Navigate to domain (establish cookies)
  348. ↓
  349. Execute fetch() via Runtime.evaluate
  350. ↓
  351. Parse response with JSONPath
  352. ↓
  353. Return data
  354. ```
  355. #### 2. Hint-Based Execution (Fallback) ~60-120 seconds
  356. If direct execution fails or no API was found:
  357. ```
  358. Inject navigation hints into task prompt
  359. ↓
  360. Agent uses hints as guidance
  361. ↓
  362. Agent discovers and calls API
  363. ↓
  364. Return data
  365. ```
  366. ### Skill File Format
  367. Skills are stored as YAML in `~/.config/browser-skills/`:
  368. ```yaml
  369. name: npm-search
  370. description: Search for packages on npmjs.com
  371. version: "1.0"
  372. # For direct execution (fast path)
  373. request:
  374. url: "https://www.npmjs.com/search?q={query}"
  375. method: GET
  376. headers:
  377. Accept: application/json
  378. response_type: json
  379. extract_path: "objects[*].package"
  380. # For hint-based execution (fallback)
  381. hints:
  382. navigation:
  383. - step: "Go to npmjs.com"
  384. url: "https://www.npmjs.com"
  385. money_request:
  386. url_pattern: "/search"
  387. method: GET
  388. # Auth recovery (if API returns 401/403)
  389. auth_recovery:
  390. trigger_on_status: [401, 403]
  391. recovery_page: "https://www.npmjs.com/login"
  392. # Usage stats
  393. success_count: 12
  394. failure_count: 1
  395. last_used: "2024-01-15T10:30:00Z"
  396. ```
  397. ### Parameters
  398. Skills support parameterized URLs and request bodies:
  399. ```yaml
  400. request:
  401. url: "https://api.example.com/search?q={query}&limit={limit}"
  402. body_template: '{"filters": {"category": "{category}"}}'
  403. ```
  404. Parameters are substituted at execution time from `skill_params`.
  405. ### Auth Recovery
  406. If an API returns 401/403, skills can trigger auth recovery:
  407. ```yaml
  408. auth_recovery:
  409. trigger_on_status: [401, 403]
  410. recovery_page: "https://example.com/login"
  411. max_retries: 2
  412. ```
  413. The system will navigate to the recovery page (letting you log in) and retry.
  414. ### Limitations
  415. - **API Discovery:** Only works if the site has an API. Sites that render everything server-side won't yield useful skills.
  416. - **Auth State:** Skills rely on browser cookies. If you're logged out, they may fail.
  417. - **API Changes:** If a site changes their API, the skill breaks. Falls back to hint-based execution.
  418. - **Complex Flows:** Multi-step workflows (login → navigate → search) may not capture cleanly.
  419. ---
  420. ## REST API Reference
  421. The server exposes REST endpoints for direct HTTP access. All endpoints return JSON unless otherwise specified.
  422. ### Base URL
  423. ```
  424. http://localhost:8383
  425. ```
  426. ### Health & Status
  427. **GET /api/health**
  428. Server health check with running task information.
  429. ```bash
  430. curl http://localhost:8383/api/health
  431. ```
  432. Response:
  433. ```json
  434. {
  435. "status": "healthy",
  436. "uptime_seconds": 1234.5,
  437. "memory_mb": 256.7,
  438. "running_tasks": 2,
  439. "tasks": [...],
  440. "stats": {...}
  441. }
  442. ```
  443. ### Tasks
  444. **GET /api/tasks**
  445. List recent tasks with optional filtering.
  446. ```bash
  447. # List all tasks
  448. curl http://localhost:8383/api/tasks
  449. # Filter by status
  450. curl http://localhost:8383/api/tasks?status=running
  451. # Limit results
  452. curl http://localhost:8383/api/tasks?limit=50
  453. ```
  454. **GET /api/tasks/{task_id}**
  455. Get full details of a specific task.
  456. ```bash
  457. curl http://localhost:8383/api/tasks/abc123
  458. ```
  459. **GET /api/tasks/{task_id}/logs** (SSE)
  460. Real-time task progress stream via Server-Sent Events.
  461. ```javascript
  462. const events = new EventSource('/api/tasks/abc123/logs');
  463. events.onmessage = (e) => console.log(JSON.parse(e.data));
  464. ```
  465. ### Skills
  466. **GET /api/skills**
  467. List all available skills.
  468. ```bash
  469. curl http://localhost:8383/api/skills
  470. ```
  471. Response:
  472. ```json
  473. {
  474. "skills": [
  475. {
  476. "name": "npm-search",
  477. "description": "Search for packages on npmjs.com",
  478. "success_rate": 92.5,
  479. "usage_count": 15,
  480. "last_used": "2024-01-15T10:30:00Z"
  481. }
  482. ],
  483. "count": 1,
  484. "skills_directory": "/Users/you/.config/browser-skills"
  485. }
  486. ```
  487. **GET /api/skills/{name}**
  488. Get full skill definition as JSON.
  489. ```bash
  490. curl http://localhost:8383/api/skills/npm-search
  491. ```
  492. **DELETE /api/skills/{name}**
  493. Delete a skill.
  494. ```bash
  495. curl -X DELETE http://localhost:8383/api/skills/npm-search
  496. ```
  497. **POST /api/skills/{name}/run**
  498. Execute a skill with parameters (starts background task).
  499. ```bash
  500. curl -X POST http://localhost:8383/api/skills/npm-search/run \
  501. -H "Content-Type: application/json" \
  502. -d '{"params": {"query": "react"}}'
  503. ```
  504. Response:
  505. ```json
  506. {
  507. "task_id": "abc123...",
  508. "skill_name": "npm-search",
  509. "message": "Skill execution started",
  510. "status_url": "/api/tasks/abc123..."
  511. }
  512. ```
  513. **POST /api/learn**
  514. Start a learning session to capture a new skill (starts background task).
  515. ```bash
  516. curl -X POST http://localhost:8383/api/learn \
  517. -H "Content-Type: application/json" \
  518. -d '{
  519. "task": "Search for TypeScript packages on npmjs.com",
  520. "skill_name": "npm-search"
  521. }'
  522. ```
  523. Response:
  524. ```json
  525. {
  526. "task_id": "def456...",
  527. "learning_task": "Search for TypeScript packages on npmjs.com",
  528. "skill_name": "npm-search",
  529. "message": "Learning session started",
  530. "status_url": "/api/tasks/def456..."
  531. }
  532. ```
  533. ### Real-Time Updates
  534. **GET /api/events** (SSE)
  535. Server-Sent Events stream for all task updates.
  536. ```javascript
  537. const events = new EventSource('/api/events');
  538. events.onmessage = (e) => {
  539. const data = JSON.parse(e.data);
  540. console.log(`Task ${data.task_id}: ${data.status}`);
  541. };
  542. ```
  543. Event format:
  544. ```json
  545. {
  546. "task_id": "abc123",
  547. "full_task_id": "abc123-full-uuid...",
  548. "tool": "run_browser_agent",
  549. "status": "running",
  550. "stage": "navigating",
  551. "progress": {
  552. "current": 5,
  553. "total": 15,
  554. "percent": 33.3,
  555. "message": "Loading page..."
  556. }
  557. }
  558. ```
  559. ---
  560. ## Architecture
  561. ### High-Level Overview
  562. ```
  563. ┌─────────────────────────────────────────────────────────────────────────┐
  564. │ MCP CLIENTS │
  565. │ (Claude Desktop, mcp-remote, CLI call) │
  566. └─────────────────────────────────┬───────────────────────────────────────┘
  567. │ HTTP POST /mcp
  568. ▼
  569. ┌─────────────────────────────────────────────────────────────────────────┐
  570. │ FastMCP SERVER │
  571. │ ┌──────────────────────────────────────────────────────────────────┐ │
  572. │ │ MCP TOOLS │ │
  573. │ │ • run_browser_agent • skill_list/get/delete │ │
  574. │ │ • run_deep_research • health_check/task_list/task_get │ │
  575. │ └──────────────────────────────────────────────────────────────────┘ │
  576. └────────┬──────────────┬─────────────────┬────────────────┬──────────────┘
  577. │ │ │ │
  578. ▼ ▼ ▼ ▼
  579. ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐
  580. │ CONFIG │ │ PROVIDERS │ │ SKILLS │ │ OBSERVABILITY │
  581. │ Pydantic │ │ 12 LLMs │ │ Learn+Run │ │ Task Tracking │
  582. └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────────┘
  583. │
  584. ▼
  585. ┌─────────────────────────┐
  586. │ browser-use │
  587. │ (Agent + Playwright) │
  588. └─────────────────────────┘
  589. ```
  590. ### Module Structure
  591. ```
  592. src/mcp_server_browser_use/
  593. ├── server.py # FastMCP server + MCP tools
  594. ├── cli.py # Typer CLI for daemon management
  595. ├── config.py # Pydantic settings
  596. ├── providers.py # LLM factory (12 providers)
  597. │
  598. ├── observability/ # Task tracking
  599. │ ├── models.py # TaskRecord, TaskStatus, TaskStage
  600. │ ├── store.py # SQLite persistence
  601. │ └── logging.py # Structured logging
  602. │
  603. ├── skills/ # Machine-learned browser skills
  604. │ ├── models.py # Skill, SkillRequest, AuthRecovery
  605. │ ├── store.py # YAML persistence
  606. │ ├── recorder.py # CDP network capture
  607. │ ├── analyzer.py # LLM skill extraction
  608. │ ├── runner.py # Direct fetch() execution
  609. │ └── executor.py # Hint injection
  610. │
  611. └── research/ # Deep research workflow
  612. ├── models.py # SearchResult, ResearchSource
  613. └── machine.py # Plan → Search → Synthesize
  614. ```
  615. ### File Locations
  616. | What | Where |
  617. |------|-------|
  618. | Config | `~/.config/mcp-server-browser-use/config.json` |
  619. | Tasks DB | `~/.config/mcp-server-browser-use/tasks.db` |
  620. | Skills | `~/.config/browser-skills/*.yaml` |
  621. | Server Log | `~/.local/state/mcp-server-browser-use/server.log` |
  622. | Server PID | `~/.local/state/mcp-server-browser-use/server.json` |
  623. ### Supported LLM Providers
  624. - OpenAI
  625. - Anthropic
  626. - Google Gemini
  627. - Azure OpenAI
  628. - Groq
  629. - DeepSeek
  630. - Cerebras
  631. - Ollama (local)
  632. - AWS Bedrock
  633. - OpenRouter
  634. - Vercel AI
  635. ---
  636. ## License
  637. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.