Camofox Mcp

CamoFox MCP

面向兼容 MCP 的 AI Agent 的 AI 驱动型反检测浏览器自动化工具。

CamoFox MCP 将 Claude Desktop、VS Code、Cursor 和 OpenClaw 等 MCP 客户端连接到 CamoFox 浏览器服务。它为 Agent 提供实用的浏览器工具集，可用于导航、交互、搜索、提取、下载和会话复用，同时依托底层基于 Camoufox 的反检测行为。

主要功能

• 提供 47 种浏览器自动化工具，涵盖导航、交互、观察、搜索、下载、会话和批处理工作流。
• 基于 CamoFox 浏览器服务和 Camoufox 构建的反检测浏览器自动化。
• 支持多标签页工作流，并跟踪状态和历史记录，还可进行清理。
• 支持会话持久化，可导入 Cookie、保存配置文件，并可选择自动保存。
• 提供节省 Token 的无障碍快照，并为复杂的 SPA 工作流提供 CSS 选择器回退方案。
• 支持兼容 OpenClaw 的 HTTP 传输，以及面向桌面 MCP 客户端的标准 stdio 支持。

快速安装

你需要运行以下两个组件：

1. camofox-browser 负责处理反检测浏览器。
2. camofox-mcp 将该浏览器提供给 MCP 客户端。

选项 A：npx + stdio

启动浏览器服务：

npx camofox-browser@latest

将 CamoFox MCP 添加到 MCP 客户端：

{
  "servers": {
    "camofox": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "camofox-mcp@latest"],
      "env": {
        "CAMOFOX_URL": "http://localhost:9377"
      }
    }
  }
}

选项 B：Docker

启动浏览器服务：

docker run -d -p 9377:9377 --name camofox-browser ghcr.io/redf0x1/camofox-browser:latest

以 HTTP 模式运行 CamoFox MCP，供 OpenClaw 等远程 MCP 客户端使用：

docker run -p 3000:8080 --rm \
  -e CAMOFOX_TRANSPORT=http \
  -e CAMOFOX_HTTP_HOST=0.0.0.0 \
  -e CAMOFOX_HTTP_API_KEY=replace-with-32-plus-random-chars \
  -e CAMOFOX_URL=http://host.docker.internal:9377 \
  ghcr.io/redf0x1/camofox-mcp:latest node dist/http.js

将 HTTP MCP 客户端配置为连接到 http://localhost:3000/mcp，并设置 Authorization: Bearer replace-with-32-plus-random-chars。

完整的客户端配置示例见 docs/getting-started.md。

快速验证

请使用 camofox-browser 2.4.7 或更高版本。浏览器 2.4.7 新增了受支持的 Windows x64 无头便携版发行包，并强化了会话范围内的导航恢复能力，同时不更改此处使用的面向 MCP 的 REST 请求格式。浏览器 2.4.6 为全新安装固定了兼容 Camoufox 的 Playwright 协议依赖项；2.4.5 新增了显式浏览器身份验证模式，包括适用于可信私有 Agent 网络的 CAMOFOX_AUTH_MODE=disabled；2.4.4 修复了持久上下文冷启动时复用 about:blank 页面的问题。

验证浏览器服务是否可访问：

curl -fsS http://localhost:9377/health

预期响应中包含 "ok":true 和 "running":true。 在尚无活动标签页的冷启动服务中，browserConnected 可能为 false；创建一个标签页即可启动浏览器会话。

工具类别

类别	工具数量	文档
健康状态	1	健康状态
标签页	3	标签页
导航	4	导航
交互	8	交互
观察	8	观察
搜索	1	搜索
会话	4	会话
配置文件	4	配置文件
下载	3	下载
提取	3	提取
批处理工作流	6	批处理
预设	1	预设

主要限制

• CamoFox MCP 不是独立的浏览器。你必须另外运行兼容的 camofox-browser 服务。
• 当 create_tab 使用 userId: "cli-default" 和 sessionKey: "default" 时，MCP 可以共享 camofox CLI 的默认浏览器配置文件/上下文，但无法可靠地连接到 CLI 已打开的标签页。导入/接管现有 CLI 标签页是未来功能。
• 有头浏览器窗口大小遵循浏览器视口/显示尺寸行为。传入 viewport，例如 { "width": 1366, "height": 768 }，或设置 CAMOFOX_VIEWPORT=1366x768 / --viewport 1366x768 作为新标签页的默认尺寸。支持的默认值范围为宽度 320..3840、高度 240..2160。
• 在 Windows x64 上，camofox-browser 2.4.7 支持在 headless=true 模式下使用便携版发行包。有头和虚拟显示模式在 Windows 上仍不受支持；toggle_display 在该平台上会拒绝这些模式。
• 无障碍树引用是主要交互方式，但 SPA 和自定义组件网站可能需要 CSS 选择器或渲染后 HTML 工具。
• 如果浏览器服务强制要求身份验证，则需要 API 密钥的操作必须在两端使用相同的 CAMOFOX_API_KEY。
• 对于使用 CAMOFOX_AUTH_MODE=disabled 的可信私有网络浏览器部署，请勿在 CamoFox MCP 中设置 CAMOFOX_API_KEY。MCP 不会发送出站浏览器身份验证标头。请确保浏览器和 MCP 均仅在可信私有网络中访问。
• 如果 HTTP 传输暴露在回环地址之外，请设置 CAMOFOX_HTTP_API_KEY，并要求客户端将其作为 Bearer 令牌发送。
• HTTP 传输主要面向远程 MCP 客户端。桌面 MCP 客户端通常使用 stdio 配置效果最佳。

安全

请将此视为浏览器控制界面。在共享或联网环境中，应隔离浏览器服务，避免广泛暴露 MCP 端点；对于入站 HTTP MCP 客户端，请使用 CAMOFOX_HTTP_API_KEY，并在浏览器服务要求身份验证时使用 CAMOFOX_API_KEY。如果浏览器服务运行在 CAMOFOX_AUTH_MODE=disabled 模式，请勿设置 CAMOFOX_API_KEY，并确保该浏览器端点仅在可信私有网络中开放。会话配置文件可能包含敏感 Cookie，应妥善保存。

文档

从 docs/README.md 的文档中心开始，然后使用 docs/getting-started.md 了解设置、验证和首个工作流示例。

贡献与许可证

贡献指南见 CONTRIBUTING.md，私下报告漏洞请参阅 SECURITY.md，MIT 许可证见 LICENSE。

自定义搜索引擎

在 MCP 服务环境中设置 CAMOFOX_SEARCH_URL_TEMPLATE，例如 https://search.example/search?q={query}&language=en，然后调用 web_search({ tabId: "tab_123", query: "café & tea", engine: "custom" })。 对于 SearXNG，请使用你的实例的 /search?q={query} URL。更改环境变量后请重启 MCP。 Google 仍为默认搜索引擎；14 个浏览器宏保持不变。

模板必须是绝对 HTTP(S) URL，且其路径或查询中必须恰好包含一个字面量 {query}， 不能出现在主机名、凭据或片段中。拒绝包含凭据的 URL。查询内容只进行一次百分号编码， 包括 Unicode 字符和 &。无效配置会导致启动失败，且不会回显 URL 或其中的令牌； 未配置时使用 custom 会返回可执行的错误信息（不会回退）。

自定义搜索使用普通浏览器 navigate，然后执行 snapshot，不会使用新的宏， 也不会直接通过 MCP HTTP 获取搜索引擎内容。浏览器 URL 验证和现有的 私有网络/SSRF 策略仍具有最高约束力，包括重定向。自托管或私有 SearXNG 需要浏览器现有的网络策略允许访问；此设置不会授予访问权限，也不会放宽该策略。 请勿在搜索 URL 中存储机密：导航过的 URL 可能会出现在工具输出、浏览器历史记录和日志中。