browser-use 集成指南：MCP 服务器、Skills 与文档 MCP 全配置详解

• 人工智能
• AI Agent
• 浏览器控制
• GUI 自动化
• MCP 服务

导读

本文围绕 browser-use 开源项目的集成能力展开，系统讲解三类入口的接入方式与底层原理：云端 HTTP MCP 服务器、本地自托管 stdio MCP 服务器，以及将云端 Skills 加载为 Agent 可复用工具端点的机制。读完本文，你将掌握在 Claude Code / Claude Desktop / Cursor / Windsurf 中配置 MCP 的完整写法、本地 MCP 服务器暴露的全部工具语义、Skills 的加载参数与 Cookie 注入逻辑，并能从源码层面理解这些集成点背后的实现细节。

关联文档：integrations.md

集成全景：一条文档串联四类能力

browser-use 的集成体系分为四个层次，分别解决不同场景下的接入问题：

前三类与browser_use/mcp/、browser_use/skills/两个模块直接对应，本文将从配置实操与源码实现两个维度分别展开。

MCP Server (Cloud)：一行命令接入云端浏览器

云端 MCP 服务器基于 HTTP 协议，地址固定为https://api.browser-use.com/mcp。它的价值在于：无需在本地安装浏览器与依赖，所有自动化任务在云端执行，客户端只需持有 API Key 即可调用。

Claude Code 接入

claude mcp add --transport http browser-use https://api.browser-use.com/mcp

--transport http指明使用 HTTP（streamable）传输，browser-use是服务器在客户端注册的名称，末尾为云端端点 URL。

Claude Desktop 接入（macOS）

编辑~/Library/Application Support/Claude/claude_desktop_config.json：

{ "mcpServers": { "browser-use": { "type": "http", "url": "https://api.browser-use.com/mcp", "headers": { "x-browser-use-api-key": "your-api-key" } } } }

关键点：云端鉴权通过x-browser-use-api-key请求头传递，需将your-api-key替换为在云端控制台生成的真实 Key。

Cursor 接入

编辑~/.cursor/mcp.json：

{ "mcpServers": { "browser-use": { "type": "http", "url": "https://api.browser-use.com/mcp", "headers": { "x-browser-use-api-key": "your-api-key" } } } }

Windsurf 接入

编辑~/.codeium/windsurf/mcp_config.json：

{ "mcpServers": { "browser-use": { "type": "http", "url": "https://api.browser-use.com/mcp", "headers": { "x-browser-use-api-key": "your-api-key" } } } }

四类客户端除配置文件路径不同外，服务器注册字段完全一致，便于跨工具迁移。

云端 MCP 工具清单与计费

云端服务器向客户端暴露的工具及计费方式如下：

browser_task的参数语义值得注意：

• task（必填）：任务的自然语言描述；
• max_steps：取值范围 1–10，默认 8，限制 Agent 的最大执行步数；
• profile_id：UUID 类型，用于指定云端浏览器配置，不传则使用默认配置。

从计费设计可以看出云端 MCP 的定位：browser_task承担重型自动化，其余工具均为免费的管理/查询类能力。

MCP Server (Local)：免费自托管的本地浏览器控制

本地 MCP 服务器基于 stdio 传输，完全免费，无需 API Key。启动命令为：

uvx --from 'browser-use[cli]' browser-use --mcp

该命令会通过uvx临时拉取带cli扩展的browser-use包，并执行其 CLI 入口的--mcp标志启动服务器。从源码看，--mcp标志在 cli.py 中被解析为mcp模式，随后通过_run_mcp_stdio_server('browser_use.mcp.server')以 stdio 传输启动 server.py 中的 MCP 服务器；--cli-mcp则对应 cli_mcp.py 的 CLI 3.0 执行模型（browser_exec工具，允许在持久的 Python 命名空间中执行浏览器 harness 辅助函数）。

Claude Desktop 配置（macOS）

{ "mcpServers": { "browser-use": { "command": "/Users/your-username/.local/bin/uvx", "args": ["--from", "browser-use[cli]", "browser-use", "--mcp"], "env": { "OPENAI_API_KEY": "your-key" } } } }

两个关键注意点：

1. command必须使用uvx的完整路径：macOS / Linux 下可先执行which uvx获取绝对路径，再填入配置，否则 Claude Desktop 可能因 PATH 环境差异找不到可执行文件；
2. env至少注入一个 LLM Key：本地服务器的 Agent 工具（retry_with_browser_use_agent）与内容提取工具依赖 LLM 推理，OPENAI_API_KEY或ANTHROPIC_API_KEY至少配置其一。服务器初始化 LLM 的逻辑位于 server.py，它从配置中读取模型与api_key，缺失时_retry_with_browser_use_agent会直接返回Error: OPENAI_API_KEY not set in config or environment。

本地 MCP 工具全景

本地服务器暴露的工具分为四组，语义已在 server.py 的handle_list_tools中定义：

Agent 级工具（完整自动化）：

• retry_with_browser_use_agent—— 接收task（必填）、max_steps（默认 100）、model、allowed_domains、use_vision（默认true）等参数，创建Agent并以max_steps上限执行完整任务。它在执行后返回步数、成功与否、最终结果、错误列表与访问过的 URL 列表，是本地端唯一的重型工具。

直接浏览器控制（需要活跃会话）：

• browser_navigate—— 跳转 URL，支持new_tab参数在新标签页打开；
• browser_click—— 按索引点击元素，或通过coordinate_x/coordinate_y进行像素级坐标点击；new_tab=true时对带href的链接会自动把相对路径换算为绝对 URL 后在新标签页打开（实现见 server.py）；
• browser_type—— 向输入框输入文本，text=""仅清空字段。该工具内置了敏感数据启发式检测：长度 ≥6 且符合邮箱特征、或长度 ≥16 且混合数字字母与.-_字符的内容会被标记为敏感信息，在返回结果与事件中只显示<email>/<credential>占位符（见 server.py）；
• browser_get_state—— 返回页面状态 JSON，包含 URL、标题、全部标签页、视口/页面尺寸、滚动位置及带索引的可交互元素列表；设置include_screenshot=true时附带截图（以 ImageContent 而非 base64 文本返回，避免 JSON 膨胀）；
• browser_scroll—— 按方向滚动页面（每次滚动 500 像素）；
• browser_go_back—— 返回浏览器历史上一页。

标签页管理：

• browser_list_tabs—— 列出所有打开标签页（返回tab_id为 target_id 后 4 位）；
• browser_switch_tab—— 按tab_id切换标签页；
• browser_close_tab—— 关闭指定标签页。

内容提取：

• browser_extract_content—— 基于query对当前页面做结构化提取，extract_links控制是否包含链接。底层复用Tools().act的extract动作（见 server.py）。

会话管理：

• browser_list_sessions—— 列出活跃会话、创建时间、最后活动时间与当前 URL；
• browser_close_session—— 按session_id关闭指定会话；
• browser_close_all—— 关闭全部会话并清理资源。

服务器还内置了会话生命周期管理：默认 10 分钟超时（session_timeout_minutes），后台清理任务每 2 分钟巡检一次，自动关闭超过空闲阈值的会话（见 server.py）。

本地环境变量

这些变量在 config.py 中有对应字段定义，并会在配置加载时写入browser_profile.headless与browser_profile.disable_security（config.py）。服务器初始化浏览器会话时（server.py），默认使用headless: False、wait_between_actions: 0.5、keep_alive: True、用户数据目录~/.config/browseruse/profiles/default的浏览器配置，并允许profile_config中的配置值覆盖这些默认值。

程序化调用本地 MCP

不依赖特定客户端时，可直接用 MCP Python SDK 以代码方式驱动：

from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def use_browser_mcp(): server_params = StdioServerParameters( command="uvx", args=["--from", "browser-use[cli]", "browser-use", "--mcp"] ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() result = await session.call_tool("browser_navigate", arguments={"url": "https://example.com"})

这里stdio_client负责建立标准输入输出双通道，ClientSession.initialize()完成协议握手，随后即可通过call_tool调用任意本地工具。这一调用链路与 client.py 中MCPClient的实现同构——后者以session.list_tools()发现工具、以session.call_tool()执行调用，并把每个工具动态注册为 browser-use 的 Action（见 client.py）。

Skills：把云端技能加载为 Agent 的可复用端点

Skills 是云端预置的、带参数 Schema 的可执行能力包。加载方式是在构造Agent时传入skills参数：

agent = Agent( task='Analyze TikTok and Instagram profiles', skills=[ 'a582eb44-e4e2-4c55-acc2-2f5a875e35e9', # TikTok Scraper 'f8d91c2a-3b4e-4f7d-9a1e-6c8e2d3f4a5b', # Instagram Scraper ], llm=ChatBrowserUse() ) await agent.run()

关键规则与注意事项

• skills=['*']加载全部技能：每个技能约向 Prompt 增加 200 tokens 上下文，技能过多会显著拉长上下文并增加成本；
• 必须设置BROWSER_USE_API_KEY：技能由云端 API 下发与执行，缺少 Key 时SkillService会直接抛出ValueError: BROWSER_USE_API_KEY environment variable is not set（见 service.py）；
• Cookie 自动注入：技能声明为cookie类型的参数会自动从浏览器会话中注入；若浏览器中缺少所需 Cookie，LLM 会收到“技能不可用”的说明并主动导航到对应站点去获取 Cookie；
• 技能可在云端控制台浏览与创建，支持按需启用/停用。

源码视角：Skills 的加载与注册

从 agent/service.py 可以看到，skills与skill_ids参数不能同时指定，skills是更简洁的推荐写法。Agent 运行时通过SkillService在单次 API 调用中批量拉取技能（service.py）：

• 通配符模式下只拉取第一页（最多 100 个技能），避免 LLM 工具过载；
• 显式 ID 模式下会分页遍历（最多 5 页）直到找齐所有请求的 ID；
• 只有状态为finished的技能才会被加载缓存。

每个技能会依据其参数 Schema 动态生成 Pydantic 模型（views.py），再通过_register_skills_as_actions（agent/service.py）注册为 Agent 的 Action，技能标题会 slug 化作为 Action 名称，并自动处理重名冲突。执行时（service.py）参数会先经过技能 Schema 的 Pydantic 校验，缺 Cookie 时抛出MissingCookieException（views.py），由上层转换成对 LLM 的“技能不可用”提示。

Documentation MCP：只读文档检索端点

文档 MCP 是只读集成，不提供任何浏览器自动化能力，专供 Agent 检索官方资料使用，且无需 API Key：

Claude Code：

claude mcp add --transport http browser-use-docs https://docs.browser-use.com/mcp

Cursor（~/.cursor/mcp.json）：

{ "mcpServers": { "browser-use-docs": { "url": "https://docs.browser-use.com/mcp" } } }

其提供的内容包括：API 参考、配置项说明、最佳实践与代码示例。适合在 Agent 撰写 browser-use 代码前先查询文档上下文，以降低幻觉、提升代码准确性。

集成选型建议

四条集成路径相互独立、可自由组合。本地 MCP 适合开发调试与数据敏感场景，云端 MCP 适合快速上手的生产调用，Skills 与文档 MCP 则分别补足“能力复用”与“知识检索”两个维度，共同构成 browser-use 完整的生态接入层。

• 人工智能
• AI Agent
• 浏览器控制
• GUI 自动化
• MCP 服务