如何启用 Odysseus 内置浏览器 MCP 服务器(@playwright/mcp)

原创2026-09-08 16:58:371,333 阅读
文章标签:人工智能AI 应用AI Agent大模型RAG工具调用MCP 服务深度研究本地部署后端前端协同办公

如何启用 Odysseus 内置浏览器 MCP 服务器(@playwright/mcp)

Odysseus 在启动时会自动注册几个内置 MCP 服务器,其中浏览器服务器(server id 为 builtin_browser,显示名 "Built-in: Browser")通过 npx 运行 @playwright/mcp,为 Agent 提供页面导航、截图和 vision 能力。这个服务器依赖 npm 包,因此它不像 memory、email 这类纯 Python 内置服务器那样开箱即用——需要先把 @playwright/mcp 放进本地 npx 缓存,重启后服务器才会注册。本文介绍如何完成这个启用流程,以及如何通过启动日志判断它是否注册成功。

工作原理:Odysseus 如何启动浏览器 MCP

注册逻辑位于 src/builtin_mcp.py。builtin_browser 的启动命令为:

npx -y @playwright/mcp@latest --headless --caps vision

在此之上,启动代码会自动补充几个参数(来自 src/builtin_mcp.py):

  • 如果在系统里找到浏览器可执行文件(按顺序探测 google-chrome、chromium、chromium-browser,以及 /opt/google/chrome/chrome、/usr/bin/google-chrome、/usr/bin/chromium、/usr/bin/chromium-browser 等固定路径),会追加 --executable-path <path>;找不到时不追加,交给 Playwright MCP 使用其默认浏览器。
  • --isolated:除非设置了 ODYSSEUS_BROWSER_ISOLATED=0(或 false/no)。
  • --no-sandbox:除非设置了 ODYSSEUS_BROWSER_NO_SANDBOX=0(或 false/no)。

服务器通过 stdio 传输由 McpManager 作为子进程托管,与 Python 内置服务器一样,注册是异步后台任务,发生在应用启动阶段。

一个环境差异值得先确认:Docker 镜像已经安装好了所需依赖——Dockerfile 中 nodejs、npm 用于提供 npx,chromium 用于提供浏览器二进制,所以容器内一般只差 npm 包本身;原生安装(Linux/macOS/Windows)则需要宿主机自己具备 Node.js(提供 npx)和一个可用的 Chrome/Chromium。

启用步骤

1. 确认 npx 可用

Odysseus 通过 PATH 查找 npx,找不到时会回退到若干常见位置(POSIX 下包括 ~/.npm-global/bin/npx、~/.local/bin/npx、/usr/local/bin/npx、/usr/bin/npx;Windows 下包括 %APPDATA%\npm\npx.cmd、C:\Program Files\nodejs\npx.cmd 等,见 src/builtin_mcp.py)。在运行 Odysseus 的同一台机器上执行:

npx --version

Docker 安装无需此步(镜像已含 nodejs/npm);原生安装若此命令不存在,需要先安装 Node.js。

2. 预装 @playwright/mcp 包(一次性)

按 docs/setup.md 的 “Built-in MCP servers (optional setup)” 一节,执行一次:

npx -y @playwright/mcp@latest --version

该命令会安装 @playwright/mcp 及 Playwright 本体(文档标注总计约 300MB),耗时取决于网络,完成后本地 npx 缓存里就有了这个包。这条命令没有副作用性的环境修改,只是把包装进 npx 缓存,可安全重复执行。

关于“是否必须预装”存在两种表述,适用条件不同:docs/setup.md 说明 npx 类内置服务器“仅当 npm 包已在本地 npx 缓存中才启动”,未缓存时会跳过并打印一条说明性的启动日志,以免全新安装被多分钟的 npm 下载阻塞或因缺少 Playwright 系统依赖而挂起;而 src/builtin_mcp.py 的注释指出,默认路径允许 npx -y 在首次启动时自行安装 @playwright/mcp,只有设置 ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1 才会回到“无网络启动”的旧行为。两者不冲突地看:手动预装(上面的命令)在任何版本行为下都能保证服务器可用;如果你希望保留无网络启动的严格行为,设置 ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1,此时包未缓存会在日志中直接给出 Fix: npx -y @playwright/mcp@latest --version 的提示。

3. 重启 Odysseus

预装后重启应用,让启动注册逻辑重新运行:

  • Docker 安装:docker compose restart odysseus(或 docker compose up -d 重建)。
  • 原生安装:停掉 uvicorn 进程后按 docs/setup.md 的方式重新启动,例如 python -m uvicorn app:app --host 127.0.0.1 --port 7000。

注意:如果环境变量里设了 ODYSSEUS_DISABLE_MCP=1(或 true/yes),所有内置 MCP 服务器(包括浏览器服务器)都不会注册,日志会显示 “Built-in MCP servers disabled via ODYSSEUS_DISABLE_MCP”。

验证注册结果

注册发生在启动阶段,结果直接体现在启动日志中(日志语句来自 src/builtin_mcp.py):

  • 正常:先打印 NPX binary resolved to: <npx 路径>,随后 Starting NPX server: Built-in: Browser (npx -y @playwright/mcp@latest --headless --caps vision ...),成功连接后输出 Built-in NPX server registered: Built-in: Browser。
  • 失败:Built-in NPX server failed to connect: Built-in: Browser,或抛出异常时输出 Built-in NPX server ... error: ...。
  • 设置了 ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1 且包未缓存时,会打印一段包含 Reason / Impact / Fix 的警告,其中 Fix 即第 2 步的 npx -y @playwright/mcp@latest --version 命令。

Docker 安装可用 docker compose logs --tail=120 odysseus 查看上述日志;确认出现 Built-in NPX server registered: Built-in: Browser 即表示浏览器 MCP 已启用。

可选环境变量

以下环境变量来自 src/builtin_mcp.py,在需要时配置后再重启生效:

变量 作用(依据源码行为)
ODYSSEUS_BROWSER_EXECUTABLE 显式指定浏览器可执行文件路径,跳过自动探测
ODYSSEUS_BROWSER_ISOLATED 置为 0/false/no 时不追加 --isolated
ODYSSEUS_BROWSER_NO_SANDBOX 置为 0/false/no 时不追加 --no-sandbox
ODYSSEUS_BROWSER_MCP_CACHE npx 缓存目录,默认 <应用目录>/data/local/playwright-mcp-cache;Playwright 浏览器下载在其 browsers 子目录
ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE 置 1 时要求包已在 npx 缓存,不做启动时网络安装

限制与排查边界

  • 浏览器服务器比 Python 内置服务器启动慢,register_builtin_servers 会让 NPX 服务器延迟 3 秒再接入(等待 Python 服务器先完成),日志里看到 “Starting NPX server” 稍晚属正常。
  • 未缓存 + 无网络安装(ODYSSEUS_BROWSER_MCP_REQUIRE_CACHE=1)时,服务器是“跳过并留痕”而不是让应用启动失败——这解释了为什么“重启后功能没出现”时应当先查日志,而不是检查应用是否起来。
  • 缺少 Playwright 系统依赖时服务器可能连不上(setup 文档提到的动机之一),此时日志会给出 failed to connect,需按 docs/setup.md 的说明先补齐环境依赖再重启。
  • builtin_browser 是内置注册的一部分,不需要在 MCP 管理界面手工添加;MCP 管理路由(添加/删除自定义 MCP 服务器)与这条内置路径互不影响。
登录后查看全文
odysseus