Content
<img src="./assets/header.png" alt="Browser Use Web UI" width="full"/>
<br/>
# browser-use MCP server & CLI
[](https://docs.browser-use.com)
[](LICENSE)
> **Project Note**: This MCP server implementation builds upon the [browser-use/web-ui](https://github.com/browser-use/web-ui) foundation. Core browser automation logic and configuration patterns are adapted from the original project.
AI-driven browser automation server implementing the Model Context Protocol (MCP) for natural language browser control and web research. Also provides CLI access to its core functionalities.
<a href="https://glama.ai/mcp/servers/@Saik0s/mcp-browser-use"><img width="380" height="200" src="https://glama.ai/mcp/servers/@Saik0s/mcp-browser-use/badge" alt="Browser-Use MCP server" /></a>
## Features
- 🧠 **MCP Integration** - Full protocol implementation for AI agent communication.
- 🌐 **Browser Automation** - Page navigation, form filling, element interaction via natural language (`run_browser_agent` tool).
- 👁️ **Visual Understanding** - Optional screenshot analysis for vision-capable LLMs.
- 🔄 **State Persistence** - Option to manage a server browser session across multiple MCP calls or connect to user's browser.
- 🔌 **Multi-LLM Support** - Integrates with OpenAI, Anthropic, Azure, DeepSeek, Google, Mistral, Ollama, OpenRouter, Alibaba, Moonshot, Unbound AI.
- 🔍 **Deep Research Tool** - Dedicated tool for multi-step web research and report generation (`run_deep_research` tool).
- ⚙️ **Environment Variable Configuration** - Fully configurable via environment variables using a structured Pydantic model.
- 🔗 **CDP Connection** - Ability to connect to and control a user-launched Chrome/Chromium instance via Chrome DevTools Protocol.
- ⌨️ **CLI Interface** - Access core agent functionalities (`run_browser_agent`, `run_deep_research`) directly from the command line for testing and scripting.
## Quick Start
### The Essentials
1. Install UV - the rocket-powered Python installer:
`curl -LsSf https://astral.sh/uv/install.sh | sh`
2. Get Playwright browsers (required for automation):
`uvx --from mcp-server-browser-use@latest python -m playwright install`
### Integration Patterns
For MCP clients like Claude Desktop, add a server configuration that's as simple as:
```json
// Example 1: One-Line Latest Version (Always Fresh)
"mcpServers": {
"browser-use": {
"command": "uvx",
"args": ["mcp-server-browser-use@latest"],
"env": {
"MCP_LLM_GOOGLE_API_KEY": "YOUR_KEY_HERE_IF_USING_GOOGLE",
"MCP_LLM_PROVIDER": "google",
"MCP_LLM_MODEL_NAME": "gemini-2.5-flash-preview-04-17",
"MCP_BROWSER_HEADLESS": "true",
}
}
}
```
```json
// Example 2: Advanced Configuration with CDP
"mcpServers": {
"browser-use": {
"command": "uvx",
"args": ["mcp-server-browser-use@latest"],
"env": {
"MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
"MCP_LLM_PROVIDER": "openrouter",
"MCP_LLM_MODEL_NAME": "anthropic/claude-3.5-haiku",
"MCP_LLM_TEMPERATURE": "0.4",
"MCP_BROWSER_HEADLESS": "false",
"MCP_BROWSER_WINDOW_WIDTH": "1440",
"MCP_BROWSER_WINDOW_HEIGHT": "1080",
"MCP_AGENT_TOOL_USE_VISION": "true",
"MCP_RESEARCH_TOOL_SAVE_DIR": "/path/to/your/research",
"MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS": "5",
"MCP_PATHS_DOWNLOADS": "/path/to/your/downloads",
"MCP_BROWSER_USE_OWN_BROWSER": "true",
"MCP_BROWSER_CDP_URL": "http://localhost:9222",
"MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",
"MCP_SERVER_LOGGING_LEVEL": "DEBUG",
"MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
}
}
}
```
```json
// Example 3: Advanced Configuration with User Data and custom chrome path
"mcpServers": {
"browser-use": {
"command": "uvx",
"args": ["mcp-server-browser-use@latest"],
"env": {
"MCP_LLM_OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
"MCP_LLM_PROVIDER": "openai",
"MCP_LLM_MODEL_NAME": "gpt-4.1-mini",
"MCP_LLM_TEMPERATURE": "0.2",
"MCP_BROWSER_HEADLESS": "false",
"MCP_BROWSER_BINARY_PATH": "/path/to/your/chrome/binary",
"MCP_BROWSER_USER_DATA_DIR": "/path/to/your/user/data",
"MCP_BROWSER_DISABLE_SECURITY": "true",
"MCP_BROWSER_KEEP_OPEN": "true",
"MCP_BROWSER_TRACE_PATH": "/path/to/your/trace",
"MCP_AGENT_TOOL_HISTORY_PATH": "/path/to/your/history",
"MCP_SERVER_LOGGING_LEVEL": "DEBUG",
"MCP_SERVER_LOG_FILE": "/path/to/your/log/mcp_server_browser_use.log",
}
}
}
```
```json
// Example 4: Local Development Flow
"mcpServers": {
"browser-use": {
"command": "uv",
"args": [
"--directory",
"/your/dev/path",
"run",
"mcp-server-browser-use"
],
"env": {
"MCP_LLM_OPENROUTER_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENROUTER",
"MCP_LLM_PROVIDER": "openrouter",
"MCP_LLM_MODEL_NAME": "openai/gpt-4o-mini",
"MCP_BROWSER_HEADLESS": "true",
}
}
}
```
**Key Insight:** The best configurations emerge from starting simple (Example 1). The .env.example file contains all possible dials.
## MCP Tools
This server exposes the following tools via the Model Context Protocol:
### Synchronous Tools (Wait for Completion)
1. **`run_browser_agent`**
* **Description:** Executes a browser automation task based on natural language instructions and waits for it to complete. Uses settings from `MCP_AGENT_TOOL_*`, `MCP_LLM_*`, and `MCP_BROWSER_*` environment variables.
* **Arguments:**
* `task` (string, required): The primary task or objective.
* **Returns:** (string) The final result extracted by the agent or an error message. Agent history (JSON, optional GIF) saved if `MCP_AGENT_TOOL_HISTORY_PATH` is set.
2. **`run_deep_research`**
* **Description:** Performs in-depth web research on a topic, generates a report, and waits for completion. Uses settings from `MCP_RESEARCH_TOOL_*`, `MCP_LLM_*`, and `MCP_BROWSER_*` environment variables. If `MCP_RESEARCH_TOOL_SAVE_DIR` is set, outputs are saved to a subdirectory within it; otherwise, operates in memory-only mode.
* **Arguments:**
* `research_task` (string, required): The topic or question for the research.
* `max_parallel_browsers` (integer, optional): Overrides `MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS` from environment.
* **Returns:** (string) The generated research report in Markdown format, including the file path (if saved), or an error message.
## CLI Usage
This package also provides a command-line interface `mcp-browser-cli` for direct testing and scripting.
**Global Options:**
* `--env-file PATH, -e PATH`: Path to a `.env` file to load configurations from.
* `--log-level LEVEL, -l LEVEL`: Override the logging level (e.g., `DEBUG`, `INFO`).
**Commands:**
1. **`mcp-browser-cli run-browser-agent [OPTIONS] TASK`**
* **Description:** Runs a browser agent task.
* **Arguments:**
* `TASK` (string, required): The primary task for the agent.
* **Example:**
```bash
mcp-browser-cli run-browser-agent "Go to example.com and find the title." -e .env
```
2. **`mcp-browser-cli run-deep-research [OPTIONS] RESEARCH_TASK`**
* **Description:** Performs deep web research.
* **Arguments:**
* `RESEARCH_TASK` (string, required): The topic or question for research.
* **Options:**
* `--max-parallel-browsers INTEGER, -p INTEGER`: Override `MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS`.
* **Example:**
```bash
mcp-browser-cli run-deep-research "What are the latest advancements in AI-driven browser automation?" --max-parallel-browsers 5 -e .env
```
All other configurations (LLM keys, paths, browser settings) are picked up from environment variables (or the specified `.env` file) as detailed in the Configuration section.
## Configuration (Environment Variables)
Configure the server and CLI using environment variables. You can set these in your system or place them in a `.env` file in the project root (use `--env-file` for CLI). Variables are structured with prefixes.
| Variable Group (Prefix) | Example Variable | Description | Default Value |
| :---------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------------------------------------- | :-------------------------------- |
| **Main LLM (MCP_LLM_)** | | Settings for the primary LLM used by agents. | |
| | `MCP_LLM_PROVIDER` | LLM provider. Options: `openai`, `azure_openai`, `anthropic`, `google`, `mistral`, `ollama`, etc. | `openai` |
| | `MCP_LLM_MODEL_NAME` | Specific model name for the provider. | `gpt-4.1` |
| | `MCP_LLM_TEMPERATURE` | LLM temperature (0.0-2.0). | `0.0` |
| | `MCP_LLM_BASE_URL` | Optional: Generic override for LLM provider's base URL. | Provider-specific |
| | `MCP_LLM_API_KEY` | Optional: Generic LLM API key (takes precedence). | - |
| | `MCP_LLM_OPENAI_API_KEY` | API Key for OpenAI (if provider is `openai`). | - |
| | `MCP_LLM_ANTHROPIC_API_KEY` | API Key for Anthropic. | - |
| | `MCP_LLM_GOOGLE_API_KEY` | API Key for Google AI (Gemini). | - |
| | `MCP_LLM_AZURE_OPENAI_API_KEY` | API Key for Azure OpenAI. | - |
| | `MCP_LLM_AZURE_OPENAI_ENDPOINT` | **Required if using Azure.** Your Azure resource endpoint. | - |
| | `MCP_LLM_OLLAMA_ENDPOINT` | Ollama API endpoint URL. | `http://localhost:11434` |
| | `MCP_LLM_OLLAMA_NUM_CTX` | Context window size for Ollama models. | `32000` |
| **Planner LLM (MCP_LLM_PLANNER_)** | | Optional: Settings for a separate LLM for agent planning. Defaults to Main LLM if not set. | |
| | `MCP_LLM_PLANNER_PROVIDER` | Planner LLM provider. | Main LLM Provider |
| | `MCP_LLM_PLANNER_MODEL_NAME` | Planner LLM model name. | Main LLM Model |
| **Browser (MCP_BROWSER_)** | | General browser settings. | |
| | `MCP_BROWSER_HEADLESS` | Run browser without UI (general setting). | `false` |
| | `MCP_BROWSER_DISABLE_SECURITY` | Disable browser security features (general setting, use cautiously). | `false` |
| | `MCP_BROWSER_BINARY_PATH` | Path to Chrome/Chromium executable. | - |
| | `MCP_BROWSER_USER_DATA_DIR` | Path to Chrome user data directory. | - |
| | `MCP_BROWSER_WINDOW_WIDTH` | Browser window width (pixels). | `1280` |
| | `MCP_BROWSER_WINDOW_HEIGHT` | Browser window height (pixels). | `1080` |
| | `MCP_BROWSER_USE_OWN_BROWSER` | Connect to user's browser via CDP URL. | `false` |
| | `MCP_BROWSER_CDP_URL` | CDP URL (e.g., `http://localhost:9222`). Required if `MCP_BROWSER_USE_OWN_BROWSER=true`. | - |
| | `MCP_BROWSER_KEEP_OPEN` | Keep server-managed browser open between MCP calls (if `MCP_BROWSER_USE_OWN_BROWSER=false`). | `false` |
| | `MCP_BROWSER_TRACE_PATH` | Optional: Directory to save Playwright trace files. If not set, tracing to file is disabled. | ` ` (empty, tracing disabled) |
| **Agent Tool (MCP_AGENT_TOOL_)** | | Settings for the `run_browser_agent` tool. | |
| | `MCP_AGENT_TOOL_MAX_STEPS` | Max steps per agent run. | `100` |
| | `MCP_AGENT_TOOL_MAX_ACTIONS_PER_STEP` | Max actions per agent step. | `5` |
| | `MCP_AGENT_TOOL_TOOL_CALLING_METHOD` | Method for tool invocation ('auto', 'json_schema', 'function_calling'). | `auto` |
| | `MCP_AGENT_TOOL_MAX_INPUT_TOKENS` | Max input tokens for LLM context. | `128000` |
| | `MCP_AGENT_TOOL_USE_VISION` | Enable vision capabilities (screenshot analysis). | `true` |
| | `MCP_AGENT_TOOL_HEADLESS` | Override `MCP_BROWSER_HEADLESS` for this tool (true/false/empty). | ` ` (uses general) |
| | `MCP_AGENT_TOOL_DISABLE_SECURITY` | Override `MCP_BROWSER_DISABLE_SECURITY` for this tool (true/false/empty). | ` ` (uses general) |
| | `MCP_AGENT_TOOL_ENABLE_RECORDING` | Enable Playwright video recording. | `false` |
| | `MCP_AGENT_TOOL_SAVE_RECORDING_PATH` | Optional: Path to save recordings. If not set, recording to file is disabled even if `ENABLE_RECORDING=true`. | ` ` (empty, recording disabled) |
| | `MCP_AGENT_TOOL_HISTORY_PATH` | Optional: Directory to save agent history JSON files. If not set, history saving is disabled. | ` ` (empty, history saving disabled) |
| **Research Tool (MCP_RESEARCH_TOOL_)** | | Settings for the `run_deep_research` tool. | |
| | `MCP_RESEARCH_TOOL_MAX_PARALLEL_BROWSERS` | Max parallel browser instances for deep research. | `3` |
| | `MCP_RESEARCH_TOOL_SAVE_DIR` | Optional: Base directory to save research artifacts. Task ID will be appended. If not set, operates in memory-only mode. | `None` |
| **Paths (MCP_PATHS_)** | | General path settings. | |
| | `MCP_PATHS_DOWNLOADS` | Optional: Directory for downloaded files. If not set, persistent downloads to a specific path are disabled. | ` ` (empty, downloads disabled) |
| **Server (MCP_SERVER_)** | | Server-specific settings. | |
| | `MCP_SERVER_LOG_FILE` | Path for the server log file. Empty for stdout. | ` ` (empty, logs to stdout) |
| | `MCP_SERVER_LOGGING_LEVEL` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`). | `ERROR` |
| | `MCP_SERVER_ANONYMIZED_TELEMETRY` | Enable/disable anonymized telemetry (`true`/`false`). | `true` |
| | `MCP_SERVER_MCP_CONFIG` | Optional: JSON string for MCP client config used by the internal controller. | `null` |
**Supported LLM Providers (`MCP_LLM_PROVIDER`):**
`openai`, `azure_openai`, `anthropic`, `google`, `mistral`, `ollama`, `deepseek`, `openrouter`, `alibaba`, `moonshot`, `unbound`
*(Refer to `.env.example` for a comprehensive list of all supported environment variables and their specific provider keys/endpoints.)*
## Connecting to Your Own Browser (CDP)
Instead of having the server launch and manage its own browser instance, you can connect it to a Chrome/Chromium browser that you launch and manage yourself.
**Steps:**
1. **Launch Chrome/Chromium with Remote Debugging Enabled:**
(Commands for macOS, Linux, Windows as previously listed, e.g., `google-chrome --remote-debugging-port=9222`)
2. **Configure Environment Variables:**
Set the following environment variables:
```dotenv
MCP_BROWSER_USE_OWN_BROWSER=true
MCP_BROWSER_CDP_URL=http://localhost:9222 # Use the same port
# Optional: MCP_BROWSER_USER_DATA_DIR=/path/to/your/profile
```
3. **Run the MCP Server or CLI:**
Start the server (`uv run mcp-server-browser-use`) or CLI (`mcp-browser-cli ...`) as usual.
**Important Considerations:**
* The browser launched with `--remote-debugging-port` must remain open.
* Settings like `MCP_BROWSER_HEADLESS` and `MCP_BROWSER_KEEP_OPEN` are ignored when `MCP_BROWSER_USE_OWN_BROWSER=true`.
## Development
```bash
# Install dev dependencies and sync project deps
uv sync --dev
# Install playwright browsers
uv run playwright install
# Run MCP server with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222 --user-data-dir="optional/path/to/user/profile"
# 2. Run inspector command with environment variables:
npx @modelcontextprotocol/inspector@latest \
-e MCP_LLM_GOOGLE_API_KEY=$GOOGLE_API_KEY \
-e MCP_LLM_PROVIDER=google \
-e MCP_LLM_MODEL_NAME=gemini-2.5-flash-preview-04-17 \
-e MCP_BROWSER_USE_OWN_BROWSER=true \
-e MCP_BROWSER_CDP_URL=http://localhost:9222 \
-e MCP_RESEARCH_TOOL_SAVE_DIR=./tmp/dev_research_output \
uv --directory . run mcp-server-browser-use
# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)
# Run CLI example
# Create a .env file with your settings (including MCP_RESEARCH_TOOL_SAVE_DIR) or use environment variables
uv run mcp-browser-cli -e .env run-browser-agent "What is the title of example.com?"
uv run mcp-browser-cli -e .env run-deep-research "What is the best material for a pan for everyday use on amateur kitchen and dishwasher?"
```
## Troubleshooting
- **Configuration Error on Startup**: If the application fails to start with an error about a missing setting, ensure all **mandatory** environment variables (like `MCP_RESEARCH_TOOL_SAVE_DIR`) are set correctly in your environment or `.env` file.
- **Browser Conflicts**: If *not* using CDP (`MCP_BROWSER_USE_OWN_BROWSER=false`), ensure no conflicting Chrome instances are running with the same user data directory if `MCP_BROWSER_USER_DATA_DIR` is specified.
- **CDP Connection Issues**: If using `MCP_BROWSER_USE_OWN_BROWSER=true`:
* Verify Chrome was launched with `--remote-debugging-port`.
* Ensure the port in `MCP_BROWSER_CDP_URL` matches.
* Check firewalls and ensure the browser is running.
- **API Errors**: Double-check API keys (`MCP_LLM_<PROVIDER>_API_KEY` or `MCP_LLM_API_KEY`) and endpoints (e.g., `MCP_LLM_AZURE_OPENAI_ENDPOINT` for Azure).
- **Vision Issues**: Ensure `MCP_AGENT_TOOL_USE_VISION=true` and your LLM supports vision.
- **Dependency Problems**: Run `uv sync` and `uv run playwright install`.
- **File/Path Issues**:
* If optional features like history saving, tracing, or downloads are not working, ensure the corresponding path variables (`MCP_AGENT_TOOL_HISTORY_PATH`, `MCP_BROWSER_TRACE_PATH`, `MCP_PATHS_DOWNLOADS`) are set and the application has write permissions to those locations.
* For deep research, ensure `MCP_RESEARCH_TOOL_SAVE_DIR` is set to a valid, writable directory.
- **Logging**: Check the log file (`MCP_SERVER_LOG_FILE`, if set) or console output. Increase `MCP_SERVER_LOGGING_LEVEL` to `DEBUG` for more details. For CLI, use `--log-level DEBUG`.
## License
MIT - See [LICENSE](LICENSE) for details.
