Browser Use Portal

MCP server enabling AI agents to control and automate web browsers through the browser-use framework.

When to Use This MCP Server

Connect this server when you need to:

• Automate complex browser interactions like form filling, multi-step navigation, and data extraction from dynamic web pages
• Build and test end-to-end workflows that require a fully rendered browser environment with JavaScript execution
• Delegate web research or scraping tasks to an AI agent that can visually interpret and interact with page content

Consider alternatives when:

• You only need to fetch static HTML or API responses where a simple HTTP client suffices
• Your automation targets are well-structured APIs rather than browser-rendered user interfaces

Quick Start

Configuration

Copy
name: browser-use-portal
type: mcp
category: browser_automation

Example Connection

Copy
claude mcp add browser-use-portal -- browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000

Available Tools

navigate:        Open a URL in the controlled browser instance
click:           Click on elements identified by selector or visual description
type-text:       Enter text into input fields and form elements
screenshot:      Capture a screenshot of the current browser viewport
extract-content: Extract structured data from the rendered page
scroll:          Scroll the page in any direction by a specified amount

Core Concepts

Browser Automation Overview

Aspect	Details
Protocol	MCP over stdio with optional HTTP proxy
Browser Engine	Chromium-based headless or headed browser
AI Integration	Uses OpenAI vision models for element identification
Session Management	Persistent browser sessions across multiple tool calls
Proxy Support	Built-in proxy on configurable port for traffic inspection
Page Interaction	Full DOM access, JavaScript execution, and cookie management

Browser Control Architecture

┌─────────────┐     ┌──────────────────┐     ┌──────────────┐
│ Claude Code  │────▶│  Browser Use     │────▶│  Chromium     │
│  (Client)    │◀────│  MCP Server      │◀────│  Browser      │
└─────────────┘     └──────────────────┘     └──────────────┘
                           │                        │
                    ┌──────┴──────┐          ┌──────┴──────┐
                    │  Proxy Port │          │  Target     │
                    │   (9000)    │          │  Website    │
                    └─────────────┘          └─────────────┘

Configuration

Parameter	Type	Default	Description
--port	integer	8000	Port for the MCP server HTTP interface
--stdio	flag	disabled	Enable stdio transport for Claude Code integration
--proxy-port	integer	9000	Port for the browser traffic inspection proxy
OPENAI_API_KEY	string	required	API key for vision model used in element identification
headless	boolean	true	Run browser without visible window for CI environments

Best Practices

1. Use Headless Mode in CI - Run with headless mode enabled in continuous integration pipelines to avoid display server dependencies. Switch to headed mode during development for visual debugging of automation steps.

2. Set Reasonable Timeouts - Web pages load at varying speeds. Configure generous timeouts for navigation actions to prevent premature failures on slow-loading pages, especially those with heavy JavaScript frameworks.

3. Isolate Browser Sessions - Create separate browser sessions for unrelated tasks to prevent cookie and state contamination. This ensures that login states and preferences from one workflow do not affect another.

4. Capture Screenshots for Debugging - Take screenshots before and after critical interaction steps. When automation fails, these screenshots provide the visual context needed to understand what the AI agent actually encountered.

5. Respect robots.txt and Rate Limits - Configure appropriate delays between requests to avoid overwhelming target servers. Automated browsing should comply with site policies and legal requirements for web scraping.

Common Issues

1. Browser Fails to Launch - Ensure Chromium dependencies are installed on your system. On Linux, install chromium-browser and required shared libraries. On macOS, the bundled Chromium should work out of the box.

2. Element Not Found Errors - Dynamic pages may not have finished rendering when the tool tries to interact. Add explicit waits or use the screenshot tool to verify page state before clicking or typing.

3. OpenAI API Key Missing - The browser-use framework requires an OpenAI API key for visual element identification. Set OPENAI_API_KEY in your environment or pass it through the MCP server configuration.