⚡ ChromeWire MCP

Real browser tabs for AI agents — through a safe localhost MCP bridge.

ChromeWire MCP connects the official Codex Chrome Extension to MCP-compatible AI CLIs:
GSD / Pi, Codex CLI, Claude Code, Cursor, Windsurf, and other agentic tools.

🌐 Project site · 🧩 Official extension · 🛡 Security · 🧰 Troubleshooting

Independent project. Not affiliated with OpenAI, Google, Chrome, or the official Codex Chrome Extension team.

🚀 Easy install via your AI agent

Copy one of these prompts into your AI coding agent / CLI assistant. The agent should inspect this repository and follow the bundled install skill at skills/install-codex-chrome-mcp/SKILL.md.

🇺🇸 English prompt

Look into this repository: https://github.com/bakhtiersizhaev/chromewire-mcp
Install ChromeWire MCP in my local AI CLI / agentic MCP setup. Add it as an MCP server for the CLI I am using. Follow the repository instructions and the agent install skill here: skills/install-codex-chrome-mcp/SKILL.md
Verify the required local prerequisites and the official Codex Chrome Extension: https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg
If the extension page is unavailable in my region, tell me that a USA IP via VPN/proxy may be required. Keep the MCP endpoint bound to 127.0.0.1. Run npm test, npm run check, npm run doctor, npm run smoke, then show me the final MCP config.

🇷🇺 Русский промпт

Посмотри этот репозиторий: https://github.com/bakhtiersizhaev/chromewire-mcp
Установи ChromeWire MCP в мой локальный AI CLI / agentic MCP setup. Добавь его как MCP server для CLI, которым я пользуюсь. Следуй инструкциям репозитория и agent install skill: skills/install-codex-chrome-mcp/SKILL.md
Проверь нужные локальные зависимости и официальный Codex Chrome Extension: https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg
Если страница расширения недоступна в моём регионе, скажи, что может понадобиться USA IP через VPN/proxy. MCP endpoint должен оставаться на 127.0.0.1. Запусти npm test, npm run check, npm run doctor, npm run smoke, потом покажи финальный MCP config.

🇨🇳 中文提示词

请查看这个仓库：https://github.com/bakhtiersizhaev/chromewire-mcp
请把 ChromeWire MCP 安装到我的本地 AI CLI / agentic MCP 环境中，并把它添加为当前 CLI 使用的 MCP server。请按照仓库说明和这个 agent install skill 执行：skills/install-codex-chrome-mcp/SKILL.md
请检查所需的本地依赖项和官方 Codex Chrome Extension：https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg
如果该扩展页面在我的地区无法打开，请告诉我可能需要使用 USA IP / VPN / proxy。MCP endpoint 必须保持绑定到 127.0.0.1。请运行 npm test、npm run check、npm run doctor、npm run smoke，然后给我最终 MCP config。

✨ Why this exists

AI browser automation is usually split between fake browser sandboxes, heavy Playwright scripts, and extension-only tools. ChromeWire MCP gives an agent a small, local, inspectable bridge into real browser tabs while keeping the control surface narrow and local-first.

🧩 Official Codex Chrome Extension

Install the official Codex Chrome Extension first:

https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg

Direct link: https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg

Availability note: the Chrome Web Store listing may be region-gated for some users. If the official extension page is unavailable in your region, you may need a USA IP via VPN/proxy before installing it. Use only legal, policy-compliant access methods for your location and account.

🏷 Repository category and tags

Category: developer tools · AI browser automation · MCP server · local-first automation

Search keywords: ChromeWire MCP, Codex Chrome Extension MCP, Model Context Protocol, Chrome MCP server, real browser automation, AI CLI browser control, Claude Code Chrome MCP, Codex CLI Chrome, Cursor MCP Chrome, Windsurf MCP Chrome, GSD Pi MCP, browser-use MCP bridge, localhost browser bridge, agentic browser automation.

🧭 What it connects

flowchart TD
    Browser[Browser profile] --> Ext[Official Codex Chrome Extension]
    Ext --> Native[Local native host / browser pipe]
    Native --> Bridge[ChromeWire MCP bridge]
    Bridge --> MCP[Local MCP stdio or HTTP endpoint]
    MCP --> GSD[GSD / Pi]
    MCP --> Codex[Codex CLI]
    MCP --> Claude[Claude Code]
    MCP --> Other[Cursor / Windsurf / other MCP clients]

🖥 Current platform status

The package includes cross-platform configuration paths. Windows uses named pipes; macOS and Linux use Unix domain sockets created by the Codex Chrome native host.

On macOS, the Codex browser socket authorizes the connecting process by code signature and process ancestry. For Codex CLI, configure ChromeWire as a stdio MCP server so Codex itself launches it:

[mcp_servers.chromewire]
command = "/Applications/Codex.app/Contents/Resources/node"
args = ["/absolute/path/to/chromewire-mcp/src/stdio.js"]
startup_timeout_sec = 20.0
tool_timeout_sec = 180.0

Starting the macOS bridge from launchd, Homebrew Node.js, or another unsigned parent can leave the extension visible but unreachable with errors such as pipe closed or Working instances: none.

🛡 Security model

• The server binds to 127.0.0.1 by default.

• Do not expose this MCP server to the public internet.

• The bridge does not expose cookies, passwords, browser history, or storage by default.

• Some tools can still open tabs, click buttons, type text, scroll pages, and read visible text from pages you explicitly target.

• Only use it on Chrome profiles and machines you own or are authorized to control.

Read docs/SECURITY.md before using this with real accounts.

✅ Requirements

• Node.js 20+

• Google Chrome

• Official Codex Chrome Extension installed and enabled: https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg

• A working native-host connection from the extension

• Windows, macOS, or Linux/Ubuntu with the official Codex native host available

🛠 Manual install

git clone https://github.com/bakhtiersizhaev/chromewire-mcp.git
cd chromewire-mcp
npm install
npm run install:codex-native-host
npm test
npm run check
npm run doctor
npm run smoke

On macOS, npm run smoke may return a macos_peer_authorization diagnostic because npm changes the process ancestry. If your final MCP config uses Codex-launched stdio, run this direct live smoke from a Codex-launched shell:

/Applications/Codex.app/Contents/Resources/node scripts/smoke.js

Stdio MCP mode

Use stdio when your MCP client can launch local commands. This is the recommended Codex CLI mode and the required mode on macOS when Codex peer authorization is active.

npm run start:stdio

Codex CLI on macOS:

[mcp_servers.chromewire]
command = "/Applications/Codex.app/Contents/Resources/node"
args = ["/absolute/path/to/chromewire-mcp/src/stdio.js"]
startup_timeout_sec = 20.0
tool_timeout_sec = 180.0

Codex CLI on Windows/Linux:

[mcp_servers.chromewire]
command = "node"
args = ["/absolute/path/to/chromewire-mcp/src/stdio.js"]
startup_timeout_sec = 20.0
tool_timeout_sec = 180.0

HTTP MCP mode

Use HTTP when your MCP client supports Streamable HTTP MCP and you want to keep the bridge running separately.

npm start

Default endpoint:

http://127.0.0.1:8962/mcp

Override host/port:

CODEX_CHROME_MCP_HOST=127.0.0.1 CODEX_CHROME_MCP_PORT=8970 npm start

🔌 MCP client config

{
  "mcpServers": {
    "chromewire": {
      "type": "http",
      "url": "http://127.0.0.1:8962/mcp"
    }
  }
}

See examples/gsd.mcp.json.

👤 Profile selection

Profiles are discovered from the local Chrome user data directory. No profile names or IDs are hardcoded.

Useful tools:

• codex_chrome_list_profiles

• codex_chrome_set_profile

• codex_chrome_health

Preferences are stored outside the repository by default:

~/.codex-chrome-mcp/profile-preference.json

🤖 Agent install skill

An AI agent can install this bridge by following skills/install-codex-chrome-mcp/SKILL.md.

📜 Attribution and forks

This project uses Apache-2.0 plus a NOTICE file. Forks, redistributions, packages, and derivative works must preserve attribution to the original project in NOTICE and in the project README or equivalent documentation.

🌍 Short descriptions

See docs/DESCRIPTIONS.md for English, Russian, and Chinese descriptions.

📚 Documentation

• docs/ARCHITECTURE.md

• docs/SECURITY.md

• docs/TROUBLESHOOTING.md

• docs/README.ru.md

• docs/README.zh.md

• docs/DESCRIPTIONS.md

• GitHub Pages site