MCP server w/ Browser Use

MCP Browser Use 服务

将 browser-use 接入 Claude Desktop 和其他兼容 MCP 的客户端的模型上下文协议（MCP）服务。

概览

此代码仓库提供了一个基于 browser-use 自动化引擎的 Beta 版 MCP 封装。它公开了一个 MCP 工具（run_browser_agent），用于协调浏览器会话、执行 browser-use Agent，并将最终结果返回给客户端。该结构将配置集中在一处，便于测试安全边界，并将上游 browser-use 迁移与 MCP 接口隔离开来。

主要功能

• 自动化浏览 – 通过 browser-use 执行自然语言指令，浏览网页、与表单交互、控制标签页、截取屏幕截图并读取页面内容。
• Agent 生命周期管理 – CustomAgent 封装 browser-use 的基础 Agent，增加历史记录导出、更丰富的提示词，以及各次运行中一致的错误处理。
• 集中管理浏览器配置 – create_browser_session 将环境变量转换为可直接使用的 BrowserSession，无需修改 Agent 逻辑即可启用持久化配置文件、代理和自定义 Chromium 标志。
• FastMCP 集成 – server.py 注册 MCP 工具、规范化配置，并确保始终清理浏览器会话。
• 客户端辅助工具 – client.py 包含异步辅助工具，供测试或其他希望在进程内运行 MCP 服务的 Python 进程使用。

项目结构

.
├── documentation/
│   ├── CONFIGURATION.md      # Detailed configuration reference
│   └── SECURITY.md           # Security considerations for running the server
├── sample.env.env           # Example environment variables for local development
├── src/mcp_browser_use/
│   ├── agent/                # Custom agent, prompts, message history, and views
│   ├── browser/              # Browser session factory and persistence helpers
│   ├── controller/           # Custom controller extensions for clipboard actions
│   ├── utils/                # LLM factory, agent state helpers, encoding utilities
│   ├── client.py             # Async helper for connecting to the FastMCP app
│   └── server.py             # FastMCP app and the `run_browser_agent` tool
└── tests/                    # Unit tests covering server helpers and agent features

入门指南

要求

• Python 3.11+
• Google Chrome 或 Chromium（用于本地自动化）
• uv，用于依赖管理（推荐）
• 可选：Claude Desktop 或其他兼容 MCP 的客户端，用于集成测试

安装

git clone https://github.com/JovaniPink/mcp-browser-use.git
cd mcp-browser-use
uv sync

将 sample.env.env 复制为 .env（或通过其他方式导出变量），并且只更新计划使用的提供方。切勿提交填写了内容的 .env 文件。

启动服务

uv run mcp-browser-use

该命令会调用 pyproject.toml 中定义的控制台脚本，启动 FastMCP 应用，并注册 run_browser_agent 工具。

与 Claude Desktop 配合使用

服务启动后，你可以在 Claude Desktop 中注册该服务，例如：

"mcpServers": {
  "mcp_server_browser_use": {
    "command": "uvx",
    "args": ["mcp-browser-use"],
    "env": {
      "MCP_MODEL_PROVIDER": "anthropic",
      "MCP_MODEL_NAME": "claude-3-5-sonnet-20241022"
    }
  }
}

调试

如需交互式调试，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/project run mcp-browser-use

Inspector 会输出一个 URL，你可以在浏览器中打开它，实时查看工具调用和响应。

配置

环境变量及其默认值的完整列表请参阅 documentation/CONFIGURATION.md。主要配置包括：

• MCP_MODEL_PROVIDER、MCP_MODEL_NAME、MCP_TEMPERATURE、MCP_MAX_STEPS、MCP_MAX_ACTIONS_PER_STEP 和 MCP_USE_VISION，用于控制大模型和 Agent 运行。
• 提供方专用的 API 密钥和端点（ANTHROPIC_API_KEY、OPENAI_API_KEY、DEEPSEEK_API_KEY、GOOGLE_API_KEY、AZURE_OPENAI_API_KEY 等）。
• 浏览器运行时标志（BROWSER_USE_HEADLESS、BROWSER_USE_EXTRA_CHROMIUM_ARGS、CHROME_PERSISTENT_SESSION、BROWSER_USE_PROXY_URL 等）。

使用 .env 搭配 python-dotenv，或使用你偏好的密钥管理器，避免将凭据纳入源代码管理。

运行测试

uv run python -m pytest -q

测试涵盖自定义 Agent 行为、浏览器配置、MCP 输入限制、密钥脱敏和实用工具。依赖更新不能仅因导入或单元测试通过就视为可以合并；解析后的环境还必须通过依赖项和安全检查。

安全

远程控制完整的浏览器实例可能会让操作者广泛访问主机。将服务暴露到不受信任的环境之前，请先阅读 documentation/SECURITY.md。 完整的文档索引和当前生效的依赖决策记录见 documentation/README.md。

MCP 工具会在分配模型或浏览器会话之前，对任务和上下文输入进行裁剪并限制其大小。 运行时步骤限制受到约束，调试日志中会省略代理设置，并会对 CDP 端点值进行脱敏，因为其中可能包含凭据。

Python 3.14/browser-use 依赖迁移仍在等待#45的处理，直至上游允许使用已修补的传递依赖版本。请勿强制设置不兼容的覆盖项，也不要忽略审计结果。

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b my-new-feature
3. 提交更改：git commit -m 'Add some feature'
4. 推送到该分支：git push origin my-new-feature
5. 发起拉取请求

欢迎提交 Bug 报告和功能建议——适用时请附上日志和复现步骤。