Skip to main content
Glama
Saik0s

Browser-Use MCP Server

by Saik0s

浏览器使用的 MCP 服务器

文档执照

项目说明:此 MCP 服务器实现基于浏览器使用/Web UI基础。核心浏览器自动化逻辑和配置模式均改编自原始项目。

人工智能驱动的浏览器自动化服务器,实现模型上下文协议 (MCP),用于自然语言浏览器控制和网络研究。

特征

  • 🧠 MCP 集成- 实现 AI 代理通信的完整协议。

  • 🌐浏览器自动化- 通过自然语言进行页面导航、表单填写、元素交互( run_browser_agent工具)。

  • 👁️视觉理解- 针对具有视觉能力的 LLM 的可选屏幕截图分析。

  • 🔄状态持久性- 跨多个 MCP 调用管理浏览器会话或连接到用户浏览器的选项。

  • 🔌多 LLM 支持- 与 OpenAI、Anthropic、Azure、DeepSeek、Google、Mistral、Ollama、OpenRouter、Alibaba、Moonshot、Unbound AI 集成。

  • 🔍深度研究工具- 用于多步骤网络研究和报告生成的专用工具( run_deep_search工具)。

  • ⚙️环境变量配置- 可通过环境变量完全配置。

  • 🔗 CDP 连接- 能够通过 Chrome DevTools 协议连接并控制用户启动的 Chrome/Chromium 实例。

Related MCP server: Browserbase MCP Server

快速入门

先决条件

  • Python 3.11 或更高版本

  • uv (快速 Python 包安装程序): pip install uv

  • 已安装 Chrome/Chromium 浏览器

  • 安装 Playwright 浏览器: uv sync然后uv run playwright install

与 MCP 客户端集成(例如 Claude Desktop)

您可以配置像 Claude Desktop 这样的客户端来连接到此服务器。将以下结构添加到客户端的配置中(例如claude_desktop_config.json ),并根据需要调整路径和环境变量:

// Example for Claude Desktop config
"mcpServers": {
    "browser-use": {
      // Option 1: Run installed package
      // "command": "uvx",
      // "args": ["mcp-server-browser-use"],

      // Option 2: Run from local development source
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-browser-use",
        "run",
        "mcp-server-browser-use"
      ],
      "env": {
        // --- CRITICAL: Add required API keys here ---
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY",
        // "OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        // "ANTHROPIC_API_KEY": "YOUR_KEY_HERE_IF_USING_ANTHROPIC",
        // ... add other keys based on MCP_MODEL_PROVIDER ...

        // --- Optional Overrides (defaults are usually fine) ---
        "MCP_MODEL_PROVIDER": "openrouter", // Use OpenRouter as provider
        "MCP_MODEL_NAME": "google/gemini-2.5-pro-exp-03-25:free", // Example OpenRouter model
        "BROWSER_HEADLESS": "true",    // Default: run browser without UI
        "BROWSER_USE_LOGGING_LEVEL": "INFO",

        // --- Example for connecting to your own browser ---
        // "MCP_USE_OWN_BROWSER": "true",
        // "CHROME_CDP": "http://localhost:9222",

        // Ensure Python uses UTF-8
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "PYTHONUTF8": "1"
      }
    }
}

**重要提示:**请确保command和args正确指向您想要运行服务器的方式(无论是从已安装的包还是从源目录运行)。在env部分中设置必要的 API 密钥。

MCP 工具

该服务器通过模型上下文协议公开以下工具:

同步工具(等待完成)

  1. run_browser_agent

    • **描述:**根据自然语言指令执行浏览器自动化任务并等待其完成。使用以MCP_为前缀的设置(例如MCP_HEADLESS 、 MCP_MAX_STEPS )。

    • 参数:

      • task (字符串,必需):主要任务或目标。

      • add_infos (字符串,可选):代理的附加上下文或提示(由custom代理类型使用)。

    • **返回:(**字符串)代理提取的最终结果或错误消息。

  2. run_deep_search

    • **描述:**针对特定主题进行深入的网络研究,生成报告并等待完成。使用以MCP_RESEARCH_为前缀的设置以及通用的BROWSER_设置(例如BROWSER_HEADLESS )。

    • 参数:

      • research_task (字符串,必需):研究的主题或问题。

      • max_search_iterations (整数,可选,默认值:10):最大搜索周期。

      • max_query_per_iteration (整数,可选,默认值:3):每个周期的最大搜索查询数。

    • **返回:(**字符串)生成的Markdown格式的研究报告,包括文件路径,或者错误信息。

配置(环境变量)

使用环境变量配置服务器。您可以在系统中设置这些变量,也可以将它们放在项目根目录下的.env文件中。

多变的

描述

必需的?

默认值

示例值

LLM 设置

MCP_MODEL_PROVIDER

使用的 LLM 提供商。请参阅以下选项。

是的

anthropic

openrouter

MCP_MODEL_NAME

所选提供商的具体型号名称。

不

claude-3-7-sonnet-20250219

anthropic/claude-3.7-sonnet

MCP_TEMPERATURE

LLM 温度(0.0-2.0)。控制随机性。

不

0.0

0.7

MCP_TOOL_CALLING_METHOD

工具调用方法('auto'、'json_schema'、'function_calling')。影响run_browser_agent 。

不

auto

json_schema

MCP_MAX_INPUT_TOKENS

run_browser_agent的 LLM 上下文的最大输入令牌。

不

128000

64000

MCP_BASE_URL

可选:LLM 提供商基本 URL 的通用覆盖。

不

特定于提供商

http://localhost:8080/v1

MCP_API_KEY

可选:LLM 提供商 API 密钥的通用覆盖(优先于提供商特定的密钥)。

不

-

sk-...

提供商 API 密钥

除非设置了MCP_API_KEY ,否则需要基于MCP_MODEL_PROVIDER 。

OPENAI_API_KEY

OpenAI 的 API 密钥。

如果使用

-

sk-...

ANTHROPIC_API_KEY

Anthropic 的 API 密钥。

如果使用

-

sk-ant-...

GOOGLE_API_KEY

Google AI(Gemini)的 API 密钥。

如果使用

-

AIza...

AZURE_OPENAI_API_KEY

Azure OpenAI 的 API 密钥。

如果使用

-

...

DEEPSEEK_API_KEY

DeepSeek 的 API 密钥。

如果使用

-

sk-...

MISTRAL_API_KEY

Mistral AI 的 API 密钥。

如果使用

-

...

OPENROUTER_API_KEY

OpenRouter 的 API 密钥。

如果使用

-

sk-or-...

ALIBABA_API_KEY

阿里云 (DashScope) 的 API 密钥。

如果使用

-

sk-...

MOONSHOT_API_KEY

Moonshot AI 的 API 密钥。

如果使用

-

sk-...

UNBOUND_API_KEY

Unbound AI 的 API 密钥。

如果使用

-

...

提供商端点

可选:覆盖默认 API 端点。

OPENAI_ENDPOINT

OpenAI API 端点 URL。

不

https://api.openai.com/v1

ANTHROPIC_ENDPOINT

Anthropic API 端点 URL。

不

https://api.anthropic.com

AZURE_OPENAI_ENDPOINT

**如果使用 Azure,则为必需。**你的 Azure 资源终结点。

如果使用

-

https://res.openai.azure.com/

AZURE_OPENAI_API_VERSION

Azure API 版本。

不

2025-01-01-preview

2023-12-01-preview

DEEPSEEK_ENDPOINT

DeepSeek API 端点 URL。

不

https://api.deepseek.com

MISTRAL_ENDPOINT

Mistral API 端点 URL。

不

https://api.mistral.ai/v1

OLLAMA_ENDPOINT

Ollama API 端点 URL。

不

http://localhost:11434

http://ollama.local:11434

OPENROUTER_ENDPOINT

OpenRouter API 端点 URL。

不

https://openrouter.ai/api/v1

ALIBABA_ENDPOINT

阿里巴巴 (DashScope) API 端点 URL。

不

https://dashscope...v1

MOONSHOT_ENDPOINT

Moonshot API 端点 URL。

不

https://api.moonshot.cn/v1

UNBOUND_ENDPOINT

未绑定的 AI API 端点 URL。

不

https://api.getunbound.ai

Ollama 专用

OLLAMA_NUM_CTX

Ollama 模型的上下文窗口大小。

不

32000

8192

OLLAMA_NUM_PREDICT

用于预测 Ollama 模型的最大标记数。

不

1024

2048

代理设置( run_browser_agent )

MCP_AGENT_TYPE

run_browser_agent的代理实现(“org”或“custom”)。

不

org

custom

MCP_MAX_STEPS

每次代理运行的最大步数。

不

100

50

MCP_USE_VISION

启用视觉功能(屏幕截图分析)。

不

true

false

MCP_MAX_ACTIONS_PER_STEP

每个代理步骤的最大操作数。

不

5

10

MCP_KEEP_BROWSER_OPEN

在run_browser_agent调用期间保持服务器管理的浏览器打开(如果MCP_USE_OWN_BROWSER=false )。

不

false

true

MCP_ENABLE_RECORDING

为run_browser_agent启用 Playwright 视频录制。

不

false

true

MCP_SAVE_RECORDING_PATH

保存代理运行视频记录的路径(如果MCP_ENABLE_RECORDING=true则必需)。

如果录音

-

./tmp/recordings

MCP_AGENT_HISTORY_PATH

保存代理历史 JSON 文件的目录。

不

./tmp/agent_history

./agent_runs

MCP_HEADLESS

专为run_browser_agent工具运行无 UI 的浏览器。

不

true

false

MCP_DISABLE_SECURITY

禁用专门针对run_browser_agent工具的浏览器安全功能(谨慎使用)。

不

true

false

深度研究设置( run_deep_search )

MCP_RESEARCH_MAX_ITERATIONS

最大搜索迭代次数,用于深入研究。

不

10

5

MCP_RESEARCH_MAX_QUERY

每次迭代的最大搜索查询数。

不

3

5

MCP_RESEARCH_USE_OWN_BROWSER

使用单独的浏览器实例进行研究(如果MCP_USE_OWN_BROWSER=true则需要CHROME_CDP )。

不

false

true

MCP_RESEARCH_SAVE_DIR

保存研究成果(报告、结果)的目录。

不

./tmp/deep_research/{task_id}

./research_output

MCP_RESEARCH_AGENT_MAX_STEPS

深入研究中的子代理的最大步骤。

不

10

15

浏览器设置(常规和特定工具覆盖)

MCP_USE_OWN_BROWSER

设置为 true 以通过CHROME_CDP连接到用户的浏览器,而不是启动新的浏览器。

不

false

true

CHROME_CDP

通过 DevTools 协议 URL 连接到现有的 Chrome。如果MCP_USE_OWN_BROWSER=true ,则必须使用此选项。

如果MCP_USE_OWN_BROWSER=true

-

http://localhost:9222

BROWSER_HEADLESS

运行浏览器时不显示可见的 UI。主要影响run_deep_search 。另请参阅MCP_HEADLESS 。

不

true

false

BROWSER_DISABLE_SECURITY

常规浏览器安全设置。另请参阅MCP_DISABLE_SECURITY 。

不

false

true

CHROME_PATH

Chrome/Chromium 可执行文件的路径。

不

-

/usr/bin/chromium-browser

CHROME_USER_DATA

Chrome 用户数据目录的路径(用于持久会话,与CHROME_CDP一起使用)。

不

-

~/.config/google-chrome/Profile 1

BROWSER_TRACE_PATH

保存 Playwright 跟踪文件的目录(用于调试)。

不

./tmp/trace

./traces

BROWSER_WINDOW_WIDTH

浏览器窗口宽度(像素)。

不

1280

1920

BROWSER_WINDOW_HEIGHT

浏览器窗口高度(像素)。

不

720

1080

服务器和日志

LOG_FILE

服务器日志文件的路径。

不

mcp_server_browser_use.log

/var/log/mcp_browser.log

BROWSER_USE_LOGGING_LEVEL

日志级别( DEBUG 、 INFO 、 WARNING 、 ERROR 、 CRITICAL )。

不

INFO

DEBUG

ANONYMIZED_TELEMETRY

启用/禁用匿名遥测( true / false )。

不

true

false

支持的 LLM 提供程序( MCP_MODEL_PROVIDER ):

openai 、 azure_openai 、 anthropic 、 google 、 mistral 、 ollama 、 deepseek 、 openrouter 、 alibaba 、 moonshot 、 unbound

连接到您自己的浏览器(CDP)

您可以将其连接到您自行启动和管理的 Chrome/Chromium 浏览器,而无需让服务器启动和管理其自身的浏览器实例。这适用于:

  • 使用您现有的浏览器配置文件(cookie、登录、扩展)。

  • 直接在您自己的浏览器窗口中观察自动化过程。

  • 调试复杂场景。

步骤:

  1. **启动 Chrome/Chromium 并启用远程调试:**打开终端或命令提示符,并运行适用于您操作系统的命令。这会指示 Chrome 监听特定端口(例如 9222)上的连接。

    • macOS:

      /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

      (如果 Chrome 安装在其他地方,请调整路径)

    • Linux:

      google-chrome --remote-debugging-port=9222
      # or
      chromium-browser --remote-debugging-port=9222
    • Windows(命令提示符):

      "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

      (如有必要,请调整 Chrome 安装路径)

    • Windows(PowerShell):

      & "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

      (如有必要,请调整 Chrome 安装路径)

    **注意:**如果端口 9222 已被使用,请选择其他端口(例如 9223)并在CHROME_CDP环境变量中使用相同的端口。

  2. **配置环境变量:**在启动 MCP 服务器之前,在.env文件或系统环境中设置以下环境变量:

    MCP_USE_OWN_BROWSER=true
    CHROME_CDP=http://localhost:9222 # Use the same port you launched Chrome with
    • MCP_USE_OWN_BROWSER=true :告诉服务器连接到现有浏览器而不是启动一个浏览器。

    • CHROME_CDP :指定服务器可以连接到浏览器的 DevTools 协议端点的 URL。

  3. **运行 MCP 服务器:**照常启动服务器:

    uv run mcp-server-browser-use

现在,当您使用run_browser_agent或run_deep_search工具时,服务器将连接到您正在运行的 Chrome 实例,而不是创建一个新的实例。

重要注意事项:

  • 使用--remote-debugging-port启动的浏览器在 MCP 服务器运行并需要与其交互时必须保持打开状态。

  • 确保CHROME_CDP URL 可以从 MCP 服务器运行的位置访问(如果在同一台机器上运行,通常为http://localhost:PORT )。

  • 使用您自己的浏览器意味着服务器会继承其状态(打开的标签页、登录的会话)。在自动化过程中请注意这一点。

  • 当MCP_USE_OWN_BROWSER=true时, MCP_HEADLESS 、 BROWSER_HEADLESS 、 MCP_KEEP_BROWSER_OPEN等设置将被忽略。窗口大小由您的浏览器窗口决定。

发展

# Install dev dependencies and sync project deps
uv sync --dev

# Install playwright browsers
uv run playwright install

# Run with debugger (Example connecting to own browser via CDP)
# 1. Launch Chrome: google-chrome --remote-debugging-port=9222
# 2. Run inspector command:
npx @modelcontextprotocol/inspector@latest \
  -e OPENROUTER_API_KEY=$OPENROUTER_API_KEY \
  -e MCP_MODEL_PROVIDER=openrouter \
  -e MCP_MODEL_NAME=anthropic/claude-3.7-sonnet \
  -e MCP_USE_OWN_BROWSER=true \
  -e CHROME_CDP=http://localhost:9222 \
  uv --directory . run mcp run src/mcp_server_browser_use/server.py
# Note: Change timeout in inspector's config panel if needed (default is 10 seconds)

故障排除

  • 浏览器冲突:如果未使用CHROME_CDP ( MCP_USE_OWN_BROWSER=false ),请确保在指定了CHROME_USER_DATA的情况下,没有其他冲突的 Chrome 实例使用相同的用户数据目录运行。

  • CDP 连接问题:如果使用MCP_USE_OWN_BROWSER=true :

    • 验证 Chrome 是否已使用--remote-debugging-port标志启动。

    • 确保CHROME_CDP中的端口与启动 Chrome 时使用的端口匹配。

    • 检查是否存在阻止与指定端口连接的防火墙问题。

    • 确保浏览器仍在运行。

  • API 错误:请仔细检查所选的MCP_MODEL_PROVIDER是否设置了正确的 API 密钥环境变量( OPENAI_API_KEY 、 ANTHROPIC_API_KEY等),或者MCP_API_KEY是否已设置。请验证密钥和端点(Azure 需要AZURE_OPENAI_ENDPOINT )。

  • 视觉问题:如果使用视觉功能,请确保MCP_USE_VISION=true ,并且您选择的 LLM 模型支持视觉。

  • 依赖项问题:运行uv sync以确保所有依赖项均已正确安装。请检查pyproject.toml 。

  • 日志记录:检查由LOG_FILE指定的日志文件(默认值: mcp_server_browser_use.log )以获取详细的错误消息。将BROWSER_USE_LOGGING_LEVEL提升至DEBUG可获得更详细的输出。

执照

MIT——详情请参阅许可证。

Available Tools

1 tool
run_browser_agentD

Handle run-browser-agent tool calls.

ParametersJSON Schema
NameRequiredDescriptionDefault
add_infosNo
taskYes

TDQS

D1.3/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure but fails completely. It doesn't indicate whether this is a read or write operation, what side effects it might have, what permissions are required, or what the expected behavior is. The phrase 'Handle... tool calls' is too vague to convey any meaningful behavioral information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is technically concise (only 5 words), this represents under-specification rather than effective brevity. The single sentence doesn't earn its place by providing meaningful information. A truly concise description would still convey essential purpose and usage information in minimal words, which this fails to do.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a tool with 2 parameters, no annotations, no output schema, and 0% schema description coverage, the description is completely inadequate. It provides no information about what the tool does, how to use it, what parameters mean, or what to expect from its operation. The description fails to compensate for any of the missing structured information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, meaning neither parameter has any description in the schema. The tool description provides no information about what the 'task' or 'add_infos' parameters mean, what format they should take, or how they affect the tool's operation. For a tool with 2 parameters and zero schema documentation, this represents a complete failure to add parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Handle run-browser-agent tool calls' is essentially a tautology that restates the tool name without explaining what the tool actually does. It doesn't specify what 'run-browser-agent' means, what resources it operates on, or what action it performs. While it mentions 'tool calls', this adds no meaningful information beyond the name itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides absolutely no guidance on when to use this tool, what context it's appropriate for, or what alternatives might exist. There are no sibling tools mentioned, but even for a standalone tool, the description fails to give any indication of its intended use case or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev1.0.0
    • First observedrun_browser_agent

TDQS

D1.8/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'run_browser_agent' has a clearly distinct purpose with no other tools to confuse it with.

Naming Consistency5/5

The naming pattern cannot be inconsistent with only one tool. The tool name 'run_browser_agent' follows a clear verb_noun pattern, and there are no other tools to deviate from this convention.

Tool Count2/5

A single tool is too few for a server named 'Browser-Use MCP Server', which suggests a broader scope for browser automation. One tool feels thin and inadequate for handling various browser-related tasks like navigation, clicking, or form filling.

Completeness1/5

The tool set is severely incomplete for browser automation. With only a 'run_browser_agent' tool, there are obvious gaps in basic operations such as opening pages, interacting with elements, or retrieving content, making it impossible for agents to perform typical browser tasks.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Enables browser automation with anti-detection features, including navigation, interaction, form filling, and session management.
    22
    26 PyPI
    10
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Provides cloud browser automation capabilities for AI agents, including creating, managing, and retrieving recordings and logs from browser sessions.
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables browser automation for AI assistants via Playwright, supporting multiple browsers, sessions, and tools for web interaction and testing.
    1,029 npm
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables plain-English browser automation via an MCP server, allowing agents to run objectives or test suites in a real browser without selectors or scripts.
    63 npm
    2
    Apache 2.0