内容
# 代码控制 Chrome MCP
[](https://www.npmjs.com/package/codex-control-chrome-mcp)
[](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml)
[](./LICENSE)
通过 MCP 将 Codex Chrome 扩展程序的流程暴露给其他 Agent 工具。
本项目允许 MCP 客户端通过已安装的 [Codex Chrome 扩展程序](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) 控制用户的普通 Chrome 配置文件。在 Agent 需要现有标签、cookie、登录会话、已安装扩展程序、截图、控制台/网络事件或原始 Chrome DevTools 协议命令时，这非常有用。
这是一个独立的社区项目。它与 OpenAI、Codex、Google 或 Chrome 无关。
- NPM：[codex-control-chrome-mcp](https://www.npmjs.com/package/codex-control-chrome-mcp)
- GitHub：[iola1999/codex-control-chrome-mcp](https://github.com/iola1999/codex-control-chrome-mcp)
- Chrome 扩展程序：[Codex Chrome 扩展程序](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg)
- 技能：[`skills/codex-control-chrome-mcp/SKILL.md`](./skills/codex-control-chrome-mcp/SKILL.md)
## 平台支持
| 平台 | 状态 | 备注 |
| --- | --- | --- |
| macOS | 已测试 | 主要支持的平台。 |
| Linux | 实验性 | 清单路径针对 `~/.config/google-chrome` 下的 Google Chrome。 |
| Windows | 不支持 | 原生消息注册在 Windows 上使用注册表键，目前尚未实现。 |
需要 Node.js 20 或更高版本。发布到 npm 的信任发布使用 GitHub Actions 中的 Node.js 24。
## 浏览器支持
两种 Chromium 浏览器使用相同的 Codex 扩展程序和相同的 `chrome-extension://` 源，因此单个清单适用于任一浏览器。
| 浏览器 | 状态 | 备注 |
| --- | --- | --- |
| Google Chrome | 已测试 | 默认目标。 |
| Microsoft Edge | 支持 | 相同的扩展程序和原生消息机制；安装到 Edge 的 `NativeMessagingHosts` 目录中。 |
命令接受 `--browser <chrome\|edge\|all>`。如果不使用该标志，`install-native-host` 将为存在的所有受支持浏览器安装，`uninstall-native-host` 将针对其以前安装的所有浏览器，而 `status` 将同时报告两者。
## 快速入门
在要自动化的 Chrome 或 Edge 配置文件中安装并启用 [Codex Chrome 扩展程序](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg)。
全局安装软件包，然后注册原生主机（自动检测存在的浏览器）：
```bash
npm install -g codex-control-chrome-mcp
codex-control-chrome-mcp install-native-host
```
全局安装提供了一个稳定的路径给原生主机，因此其启动器直接针对已安装的 CLI 执行 Node，而无需每次连接的 `npx` 成本。要显式针对一个浏览器：
```bash
codex-control-chrome-mcp install-native-host --browser edge
```
通过已安装的二进制文件配置 Agent 使用 MCP stdio 服务器：
```json
{
"type": "stdio",
"command": "codex-control-chrome-mcp",
"args": ["--stdio"],
"startup_timeout_sec": 30
}
```
如果您的 MCP 客户端没有继承包含 npm 全局二进制目录的 shell `PATH`（常见于 GUI 应用程序），请使用 `npm prefix -g` 的绝对路径 — 例如 `/opt/homebrew/bin/codex-control-chrome-mcp` — 作为 `command`。
检查状态和卸载：
```bash
codex-control-chrome-mcp status
codex-control-chrome-mcp uninstall-native-host # 恢复以前的 Codex 原生主机清单
```
### 无全局安装
`npx -y codex-control-chrome-mcp@latest <command>` 仍然适用于所有命令。请注意，`npx … install-native-host` 编写一个启动器，在每次扩展程序连接时重新运行 `npx`；冷或被逐出的 npx 缓存可能会增加数秒，并且可能超过扩展程序的连接超时（此时桥看起来卡住且无法连接）。安装程序检测到 npx 临时副本并保留该启动器作为备用 — 全局安装并重新运行 `install-native-host` 以获取快速、稳定的路径。
## Agent 技能
如果您的 Agent 支持技能，请安装或引用捆绑的技能文件夹：
```text
skills/codex-control-chrome-mcp
```
技能文档介绍了推荐的 MCP 工具顺序，用于：
- 状态检查
- 标签列表和声明
- CDP 附件和命令执行
- 截图
- 网络和控制台事件读取
- 标签终结
## 安全注意事项
本项目控制用户的普通 Chrome 配置文件。连接到它的 MCP 客户端可以检查页面内容并向声明的标签发送原始 CDP 命令。
仅在您拥有或被明确授权自动化的机器和 Chrome 配置文件中安装和运行它。不要在问题或日志中发送浏览器 cookie、密码存储、配置文件数据库、令牌或私有会话文件。
有关安全模型和报告过程，请参见 [SECURITY.md](./SECURITY.md)。
## 工作原理
Codex Chrome 扩展程序不需要外部 Chrome 远程调试端口。它使用 Chrome 原生消息和扩展程序的 `chrome.debugger` 权限：
```text
Chrome 扩展程序
-> chrome.runtime.connectNative("com.openai.codexextension")
-> codex-control-chrome-mcp 原生主机
-> 本地 MCP 桥接套接字
-> chrome.debugger.attach / chrome.debugger.sendCommand
-> CDP
```
由于控制入口点位于普通 Chrome 配置文件中，因此可以重用现有的 cookie、登录会话、标签页和扩展程序。
阅读更多：
- [架构](./docs/architecture.md)
- [故障排除和调试手册](./docs/troubleshooting.md)
- [安装和卸载](./docs/install.md)
- [官方套接字探测说明](./docs/socket-probe.md)
- [发布流程](./docs/release.md)
## 开发
安装依赖项：
```bash
npm ci
```
运行检查：
```bash
npm run ci
```
在本地运行 MCP 服务器：
```bash
node ./bin/codex-control-chrome-mcp.js --stdio
```
在本地运行原生主机模式进行开发：
```bash
node ./bin/codex-control-chrome-mcp.js --native-host
```
## 故障排除
### Codex 更新停止了桥接
Codex 应用程序/扩展程序更新重新注册了它们自己的 `com.openai.codexextension` 原生消息清单，这覆盖了本项目的代理注册（捆绑的主机二进制文件甚至在发布之间被重命名）。症状是 `status` 显示 `sockets: []`、`registered: false` 和一个返回到 Codex 包内的清单 `path`。
MCP stdio 服务器现在 **自我修复**：在启动时，它在检测到清单被恢复时重新声明清单，因此您通常不需要重新运行 `install-native-host`。由于 Chrome 仅在扩展程序重新连接时读取清单，**在 Codex 更新后重新加载 Codex Chrome 扩展程序（或重新启动 Chrome）一次**，以使桥接恢复。设置 `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1` 以禁用自动重新注册。
如果 Codex 应用程序集成停止工作，请卸载此原生主机以恢复备份的清单：
```bash
npx -y codex-control-chrome-mcp@latest uninstall-native-host
```
如果标签页或 CDP 工具失败，请使用捆绑的技能工作流：再次列出标签页，仅声明当前标签页 ID，在原始 CDP 调用之前附加，并在启用相关域后读取 CDP 事件。
### “调试器未附加” / 并发下的 flaky CDP
CDP 工具自 1.4.0 起自我修复陈旧调试器附件（验证附件，并通过 `detach` → 重新附件 → 重试恢复丢失的附件）。如果您仍然看到附件不稳定 — 最可能是当多个浏览器控制堆栈共享一个 Chrome 并竞争单个标签页调试器时 — 请参见 [故障排除和调试手册](./docs/troubleshooting.md)，了解根本原因、参考点（官方客户端、扩展程序服务工作线程）和 `scripts/concurrency-check.mjs` 浸泡测试。
有关完整的每个浏览器检查列表，请参见 [安装和卸载](./docs/install.md#troubleshooting)（`registered` 标志和主机 `classification`）。
## 许可证
MIT
