MCP 服务器

Browser-Use MCP Server

通过 browser-use 库集成，利用自定义功能和基于代理的交互来促进浏览器自动化。

网络自动化与隐身

AI集成系统

访问服务器

Tools

run_browser_agent

Handle run-browser-agent tool calls.

README

browser-use MCP 服务器

项目说明: 此 MCP 服务器的实现基于 browser-use/web-ui 项目。核心浏览器自动化逻辑和配置模式均改编自原始项目。

AI 驱动的浏览器自动化服务器，实现了模型上下文协议 (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 实例。

快速开始

前提条件

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)，根据需要调整路径和环境变量：

// Claude Desktop 配置示例
"mcpServers": {
    "browser-use": {
      // 选项 1: 运行已安装的包
      // "command": "uvx",
      // "args": ["mcp-server-browser-use"],

      // 选项 2: 从本地开发源运行
      "command": "uvx",
      "args": [
        "mcp-server-browser-use"
      ],
      "env": {
        // --- 关键: 在此处添加所需的 API 密钥 ---
        "OPENAI_API_KEY": "YOUR_KEY_HERE_IF_USING_OPENAI",
        "ANTHROPIC_API_KEY": "YOUR_KEY_HERE_IF_USING_ANTHROPIC",
        // ... 根据 MCP_MODEL_PROVIDER 添加其他密钥 ...

        // --- 可选覆盖 (默认值通常可以) ---
        "MCP_MODEL_PROVIDER": "anthropic", // 默认提供商
        "MCP_MODEL_NAME": "claude-3-7-sonnet-20250219", // 默认模型
        "BROWSER_HEADLESS": "true",    // 默认: 在没有 UI 的情况下运行浏览器
        "BROWSER_USE_LOGGING_LEVEL": "INFO",

        // --- 连接到您自己的浏览器的示例 ---
        // "MCP_USE_OWN_BROWSER": "true",
        // "CHROME_CDP": "http://localhost:9222",

        // 确保 Python 使用 UTF-8
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "PYTHONUTF8": "1"
      }
    }
}

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

MCP 工具

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

同步工具 (等待完成)

run_browser_agent
- 描述: 根据自然语言指令执行浏览器自动化任务，并等待其完成。使用带有 MCP_ 前缀的设置 (例如，MCP_HEADLESS、MCP_MAX_STEPS)。
- 参数:
  - task (字符串，必需): 主要任务或目标。
  - add_infos (字符串，可选): 代理的其他上下文或提示 (由 custom 代理类型使用)。
- 返回: (字符串) 代理提取的最终结果或错误消息。
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`	`openai`
`MCP_MODEL_NAME`	所选提供商的特定模型名称。	否	`claude-3-7-sonnet-20250219`	`gpt-4o`
`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_MODEL_PROVIDER` 必需，除非设置了 `MCP_API_KEY`。
`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`	Unbound 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、登录名、扩展程序)。
直接在您自己的浏览器窗口中观察自动化。
调试复杂的场景。

步骤：

启动启用远程调试的 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
# 或
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 环境变量中使用相同的端口。
配置环境变量： 在启动 MCP 服务器之前，在您的 .env 文件或系统环境中设置以下环境变量：
```
MCP_USE_OWN_BROWSER=true
CHROME_CDP=http://localhost:9222 # 使用您启动 Chrome 的相同端口
```
- MCP_USE_OWN_BROWSER=true：告诉服务器连接到现有浏览器，而不是启动一个浏览器。
- CHROME_CDP：指定服务器可以连接到您的浏览器 DevTools 协议端点的 URL。
运行 MCP 服务器： 像往常一样启动服务器：
```
uv run mcp-server-browser-use
```

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

重要注意事项：

使用 --remote-debugging-port 启动的浏览器必须保持打开状态，而 MCP 服务器正在运行并且需要与其交互。
确保可以从 MCP 服务器运行的位置访问 CHROME_CDP URL (如果在同一台计算机上运行，通常为 http://localhost:PORT)。
使用您自己的浏览器意味着服务器会继承其状态 (打开的选项卡、登录的会话)。在自动化期间请注意这一点。
当 MCP_USE_OWN_BROWSER=true 时，将忽略 MCP_HEADLESS、BROWSER_HEADLESS、MCP_KEEP_BROWSER_OPEN 等设置。窗口大小由您的浏览器窗口确定。

开发

# 安装开发依赖项并同步项目依赖项
uv sync --dev

# 安装 playwright 浏览器
uv run playwright install

# 使用调试器运行 (通过 CDP 连接到自己的浏览器的示例)
# 1. 启动 Chrome: google-chrome --remote-debugging-port=9222
# 2. 运行 inspector 命令:
npx @modelcontextprotocol/inspector@latest \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -e MCP_MODEL_PROVIDER=anthropic \
  -e MCP_MODEL_NAME=claude-3-7-sonnet-20250219 \
  -e MCP_USE_OWN_BROWSER=true \
  -e CHROME_CDP=http://localhost:9222 \
  uv --directory . run mcp run src/mcp_server_browser_use/server.py
# 注意: 如果需要，请更改 inspector 配置面板中的超时 (默认为 10 秒)

故障排除

浏览器冲突：如果不使用 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 - 有关详细信息，请参阅 LICENSE。