# @askjo/camofox-browser-mcp 中文文档

规范地址：https://npmcn.com/package/%40askjo/camofox-browser-mcp/

版本：1\.18\.1
npm 元数据更新时间：2026-10-05T02:46:47.496Z
中文译文更新时间：2026-11-06T23:34:06.708Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40askjo/camofox-browser-mcp
原文对照：https://npmcn.com/package/%40askjo/camofox-browser-mcp/?lang=original
项目主页：https://github.com/jo-inc/camofox-browser/tree/master/mcp#readme
源码仓库：https://github.com/jo-inc/camofox-browser

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：39.2 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22
- 运行依赖：1 个
- 首次发布：2026-08-02T02:39:11.149Z
- 最新版本发布：2026-10-05T02:46:47.157Z
- 近 30 天下载量：2200（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

独立stdio MCP服务器曝光相机-浏览器REST API作为MCP工具(Claude Code, Codex, agy, Cursor, opencode). 已运行的 Camofox- 浏览器 REST 服务器的代理 —— 本身不需要浏览器二进制, Playwright, 或核心 ser

## 安装

```sh
npm install @askjo/camofox-browser-mcp
```

也可以使用：`pnpm add @askjo/camofox-browser-mcp`、`yarn add @askjo/camofox-browser-mcp`、`bun add @askjo/camofox-browser-mcp`

## README

# camofox-浏览器 MCP 服务器

一个独立的 [示范背景协议](https://modelcontextprotocol.io/) 服务器将相机-浏览器暴露于任何MCP相容的主机——克洛德码(Claude Code),Cursor等,而不需要OpenClaw.

它映射出现有的 OpenClaw 插件 **1:1 (中文(简体) )**:相同的11个工具名,相同的JSON-Schema参数,以及相同的REST路由. 无论是代理通过OpenClaw还是MCP到达相模克,行为都是一样的.

MCP服务器的初始实施由下列因素促成: [@epicagas (西班牙语)](https://github.com/epicsagas)。 。 。 .

## 建筑

MCP服务器是Camofox REST服务器上的一个瘦小的stdio客户端. 两块:

-   **REST 服务器** (单位:千美元)`server.js`)——发射Camoufox,曝光HTTP API上 `:9377`运行 **一次**它会保持上升.
-   **MCP 服务器** (单位:千美元)`mcp/server.mjs`,暴露为 `camofox-browser-mcp` bin)——将MCP工具调用翻译为REST调用. 克劳德代码产出一个 **每届会议**。 。 。 .

注册 MCP 服务器 **没有** 需要进入相机浏览器的检查。 下面的例子从任何目录中都可以找到.

`mcp/` 也是一个 **可独立安装的软件包** (单位:千美元)`@askjo/camofox-browser-mcp`本身 `package.json`) (中文(简体) ). 只能靠什么 `@modelcontextprotocol/sdk` 没有 `camoufox-js`, (中文(简体) ), `playwright-core`, (中文(简体) ), `express`,或核心服务器所拉入的~300MB浏览器二进制下载. 工具名、 JSON-Schema 参数、 REST 路由和响应形状定义 `mcp/lib/tool-contracts.mjs`单人包里装的 OpenClaw 插件 (PDF)`plugin.ts`)导入同一种犬形模块,因此两个主机无法漂移. 见 **备选案文D** 下方仅需要MCP适配器(例如指向) `CAMOFOX_BASE_URL` 在 REST 服务器运行到其他地方.

## 1\. 启动REST服务器

克隆回波并启动服务器( 第一次运行时一次性二进制下载) :

```bash
git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser
npm install   # downloads Camoufox (~300MB) on first run
npm start     # → http://localhost:9377
```

这仍然在背景中运行。 之后就不用你来管了.

## 2\. 安装 `camofox-browser-mcp` 选项

MCP服务器对每个主机都是一样的——不同之处只是您粘贴的配置文件. 首先,让 `camofox-browser-mcp` 在您的路径上可用 bin 。 选一:

```bash
# Option A — npm link (if you have the source checkout; picks up local edits)
cd camofox-browser && npm link

# Option B — global install (no source checkout needed)
npm install -g @askjo/camofox-browser

# Option C — npx (no install; runs the published standalone adapter)
#   Use this wherever a command is expected below.
npx -y @askjo/camofox-browser-mcp

# Option D — MCP adapter only, no core server deps (lightest footprint)
#   Skips camoufox-js/playwright-core/express and the browser binary download —
#   use this if a camofox-browser REST server is already running (locally or
#   remotely) and you only need the stdio adapter.
git clone https://github.com/jo-inc/camofox-browser && cd camofox-browser/mcp
npm install   # installs only @modelcontextprotocol/sdk (~24MB, no postinstall)
npm link      # camofox-browser-mcp now resolves from any directory
```

从任何目录校验本解析 :

```bash
which camofox-browser-mcp   # → .../bin/camofox-browser-mcp
```

## 3\. 与东道国登记

所有5个主机都说标准MCP,所以都运行相同 `camofox-browser-mcp` 宾. 在下面选择您的主机配置片段 .

### 克劳德代码

```bash
# CLI (user scope = available in every project)
claude mcp add camofox-browser -s user -- camofox-browser-mcp
```

或进入 `~/.claude.json` (用户)/ `.mcp.json` (项目,入帐):

```json
{
  "mcpServers": {
    "camofox-browser": {
      "command": "camofox-browser-mcp"
    }
  }
}
```

### 代码 CLI

`~/.codex/config.toml` (用户)或 `.codex/config.toml` (项目,只信任的迪尔斯):

```toml
[mcp_servers.camofox-browser]
command = "camofox-browser-mcp"
env = { CAMOFOX_BASE_URL = "http://localhost:9377" }
```

### 反重力/ 阳性

全球 `~/.gemini/config/mcp_config.json` 或工作空间 `.agents/mcp_config.json`数字 :

```json
{
  "mcpServers": {
    "camofox-browser": {
      "command": "camofox-browser-mcp"
    }
  }
}
```

### 光标

全球 `~/.cursor/mcp.json` 或项目 `.cursor/mcp.json` (填写如下):

```json
{
  "mcpServers": {
    "camofox-browser": {
      "command": "camofox-browser-mcp"
    }
  }
}
```

(或取自UI:设置 光标设置 MCP 添加新MCP服务器

### 打开代码

`opencode.json` 项目根,或全局 `~/.config/opencode/opencode.json`数字 :

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "camofox-browser": {
      "type": "local",
      "command": ["camofox-browser-mcp"]
    }
  }
}
```

### 常见: env vars 从源回落

如果您需要 cookie 导入或非默认的 REST URL, 请添加 env 。 Claude 代码示例:

```bash
claude mcp add camofox-browser -s user \
  --env CAMOFOX_BASE_URL=http://localhost:9377 \
  --env CAMOFOX_API_KEY=<key> \
  -- camofox-browser-mcp
```

对于其他主机,请在 `env` 编号 : `environment` 该主机的片段.

**从源回落** (除非你进入了出票环节 且没有链接到本站):

```bash
# Replace `camofox-browser-mcp` with `node /absolute/path/to/mcp/server.mjs`
claude mcp add camofox-browser -- node /Users/you/src/camofox-browser/mcp/server.mjs
```

> 总是喜欢 `camofox-browser-mcp` bin(以上选项A/B/C/D)。 这个 `node ./mcp/server.mjs` 窗体为 **路径依赖** ——取出外的相对路径中断.

## 4\. 核实

| 东道主 | 如何核实 |
| --- | --- |
| 克劳德代码 | `/mcp` —— 说 `camofox-browser` 显示已连接 |
| 代码 CLI | `codex` 然后检查 MCP 服务器列表 |
| 不错 | `/mcp` 覆盖在 `agy` 国 际 |
| 光标 | 设置 — MCP — 服务器显示绿色 |
| 打开代码 | `opencode mcp list` |

您应该看到11个工具 : `camofox_create_tab`, (中文(简体) ), `camofox_snapshot`, (中文(简体) ), `camofox_click`, (中文(简体) ), `camofox_type`, (中文(简体) ), `camofox_navigate`, (中文(简体) ), `camofox_scroll`, (中文(简体) ), `camofox_screenshot`, (中文(简体) ), `camofox_evaluate`, (中文(简体) ), `camofox_list_tabs`, (中文(简体) ), `camofox_close_tab`, (中文(简体) ), `camofox_import_cookies`。 。 。 .

## 工具

| 工具 | 目的 |
| --- | --- |
| `camofox_create_tab` | 打开 URL = 返回 `tabId` |
| `camofox_snapshot` | 无障碍快照 + 元素 refs (`e1`, (中文(简体) ), `e2`,.) + 截图 |
| `camofox_navigate` | 转到 URL **或者说** 使用搜索宏( e)`@google_search`, (中文(简体) ), `@reddit_search`, (...) (中文(简体) ) |
| `camofox_click` | 按元素 ref 点击 (`e1`)或 CSS 选择器 |
| `camofox_type` | 将文本输入参考/选择器, 可选 `pressEnter` |
| `camofox_scroll` | 按像素滚动(在懒惰的页面上不可靠——偏好) `camofox_evaluate`(中文(简体) ) |
| `camofox_screenshot` | 独立截图 |
| `camofox_evaluate` | 在页面背景中运行JS——提取数据,调用页面API,滚动通过 `window.scrollTo` |
| `camofox_list_tabs` | 在此会话中列出打开的标签 |
| `camofox_close_tab` | 关闭标签 |
| `camofox_import_cookies` | 导入 Netscape cookie 文件( 需要) `CAMOFOX_API_KEY`(中文(简体) ) |

## 工作流程

每一次互动都遵循同样的形状—— **动作前的快照**数字 :

1.  `create_tab({ url })` → `tabId`
2.  `snapshot({ tabId })` − 元素参考(`e1`, (中文(简体) ), `e2`, (...) (中文(简体) )
3.  `click`编号 :`type` 使用这些参考文献
4.  `snapshot` 再次读取新状态
5.  `close_tab` 完成时

元素 refs 清晰且首选于 CSS 选择器 — 一个匹配多个元素返回的选取器 `422 strict mode violation`,在此情况下重拍并点击 ref.

## 环境变量

| 瓦尔 | 默认 | 目的 |
| --- | --- | --- |
| `CAMOFOX_BASE_URL` | `http://localhost:9377` | REST 服务器 URL |
| `CAMOFOX_USER_ID` | `mcp-<random>` | 会话隔离( 一个 MCP 服务器 = 一个相片会话) |
| `CAMOFOX_SESSION_KEY` | `default` | 用户内的标签分区 |
| `CAMOFOX_ACCESS_KEY` | _(未设定)_ | 全球无记名符号 给 REST 服务器( 超级密钥) 配角 。 如果设定,转发为 `Authorization: Bearer <key>` 打开 **每个** 自动调用工具 —— 必须匹配 REST 服务器本身 `CAMOFOX_ACCESS_KEY`。如果没有此选项, 全球认证的 REST 服务器将拒绝除 cookie 导入以外的所有工具调用 . |
| `CAMOFOX_API_KEY` | _(未设定)_ | 自选的秘方小饼干导入. 可选择本地主机; 远程/ 生产时需要, 必须匹配 REST 服务器的 `CAMOFOX_API_KEY`。只影响 `camofox_import_cookies`。 。 。 . |

## 解决问题

-   **`503 session_expired` 编号 : `tab create timed out`** —— REST 服务器的浏览器会话已死(往往是在先前的失败的呼叫使其不稳定后). 重新开始 `npm start`。 。 。 .
-   **`camofox_scroll` 返回时 `{ok:true}` 但页面不动** — 期望在懒惰负载/ 虚拟滚动页面上; 服务器的 `mouse.wheel` 那边没有 使用 `camofox_evaluate` 与 `window.scrollTo` 编号 : `scrollBy`。 。 。 .
-   **`422 strict mode violation ... resolved to N elements`** 打开 `click` —— CSS 选择器匹配多个元素. 重拍并点击元素 ref.
-   **`403 Forbidden` 打开 `camofox_import_cookies`** —— REST 服务器和 MCP 服务器之间的密钥不匹配, 或点击远程服务器而不 `CAMOFOX_API_KEY`。 。 。 .
-   **`401`编号 :`403` 每个工具调用, 不仅仅是 cookie 导入** ——REST服务器已经 `CAMOFOX_ACCESS_KEY` 设置。 设置相同 `CAMOFOX_ACCESS_KEY` 在 MCP 服务器的嵌入( 见上文表格) 中—— 它自动转发为 `Authorization: Bearer` 一旦设定.

## 测试(开发者)

两层,涵盖不同的东西:

```bash
# 1. `test:mcp` installs the standalone adapter's locked dependencies, then
#    runs the in-repository and packed-tarball handshake tests. Neither needs
#    a REST server.
npm run test:mcp

# 2. Mock-HTTP contract tests — verifies the actual REST traffic each tool
#    produces: routes, methods, request bodies, CAMOFOX_ACCESS_KEY/CAMOFOX_API_KEY
#    auth headers, cookie parsing (Netscape file → `{ cookies }` body, never a
#    path), screenshot decoding, and error handling. Mocked REST server — no
#    live camofox-browser process needed. This is what makes the "OpenClaw and
#    MCP send identical requests" claim verifiable, not just asserted.
NODE_OPTIONS='--experimental-vm-modules' npx jest tests/unit/mcp-contracts.test.js
```

装入的tarball 检查安装生成的 `@askjo/camofox-browser-mcp` 握手前在空目录中放入焦油. 它捕捉到的进口量在独立包件之外.

## 常见问题

### @askjo/camofox-browser-mcp 是什么？

独立stdio MCP服务器曝光相机-浏览器REST API作为MCP工具\(Claude Code, Codex, agy, Cursor, opencode\)\. 已运行的 Camofox- 浏览器 REST 服务器的代理 —— 本身不需要浏览器二进制, Playwright, 或核心 ser

### 如何安装 @askjo/camofox-browser-mcp？

在项目目录运行 npm install @askjo/camofox-browser-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 camofox-browser-mcp，可以用 npx camofox-browser-mcp 直接运行。

### @askjo/camofox-browser-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/askjo\_\_camofox-browser-mcp 是否存在。

### @askjo/camofox-browser-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @askjo/camofox-browser-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @askjo/camofox-browser-mcp 可以商用吗？

@askjo/camofox-browser-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @askjo/camofox-browser-mcp 的下载量有多少？

根据 npm 官方下载统计，@askjo/camofox-browser-mcp 在 2026/10/07 – 2026/11/05 这 30 天内被下载 2,200 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @askjo/camofox-browser-mcp 还在维护吗？

最新版本 1\.18\.1 发布于 2026/10/05（1 个月前）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/08/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。