浏览器使用的 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 实例。

快速入门

先决条件

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 工具

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

同步工具（等待完成）

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`	`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、登录、扩展）。
直接在您自己的浏览器窗口中观察自动化过程。
调试复杂场景。

步骤：

**启动 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环境变量中使用相同的端口。
**配置环境变量：**在启动 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。
**运行 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——详情请参阅许可证。

Browser-Use MCP Server

Integrations