{"id":51302715,"url":"https://github.com/iola1999/codex-control-chrome-mcp","last_synced_at":"2026-06-30T21:32:27.037Z","repository":{"id":367577582,"uuid":"1281398939","full_name":"iola1999/codex-control-chrome-mcp","owner":"iola1999","description":"MCP server and native host bridge for controlling Chrome through the Codex Chrome extension.","archived":false,"fork":false,"pushed_at":"2026-06-26T15:47:30.000Z","size":30,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T16:23:18.041Z","etag":null,"topics":["agent-tools","browser-automation","cdp","chrome","chrome-extension","codex","control-chrome","mcp","native-messaging"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/codex-control-chrome-mcp","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iola1999.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-26T14:15:07.000Z","updated_at":"2026-06-26T15:47:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iola1999/codex-control-chrome-mcp","commit_stats":null,"previous_names":["iola1999/codex-chrome-use-mcp"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/iola1999/codex-control-chrome-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iola1999%2Fcodex-control-chrome-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iola1999%2Fcodex-control-chrome-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iola1999%2Fcodex-control-chrome-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iola1999%2Fcodex-control-chrome-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iola1999","download_url":"https://codeload.github.com/iola1999/codex-control-chrome-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iola1999%2Fcodex-control-chrome-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34984784,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-tools","browser-automation","cdp","chrome","chrome-extension","codex","control-chrome","mcp","native-messaging"],"created_at":"2026-06-30T21:32:26.198Z","updated_at":"2026-06-30T21:32:26.974Z","avatar_url":"https://github.com/iola1999.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Control Chrome MCP\n\n[![npm version](https://img.shields.io/npm/v/codex-control-chrome-mcp.svg)](https://www.npmjs.com/package/codex-control-chrome-mcp)\n[![CI](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/iola1999/codex-control-chrome-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\nExpose the Codex Chrome Extension flow to other Agent tools through MCP.\n\nThis project lets MCP clients control the user's normal Chrome profile through the installed [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg). It is useful when an Agent needs existing tabs, cookies, logged-in sessions, installed extensions, screenshots, console/network events, or raw Chrome DevTools Protocol commands.\n\nThis is an independent community project. It is not affiliated with OpenAI, Codex, Google, or Chrome.\n\n- NPM: [codex-control-chrome-mcp](https://www.npmjs.com/package/codex-control-chrome-mcp)\n- GitHub: [iola1999/codex-control-chrome-mcp](https://github.com/iola1999/codex-control-chrome-mcp)\n- Chrome Extension: [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg)\n- Skill: [`skills/codex-control-chrome-mcp/SKILL.md`](./skills/codex-control-chrome-mcp/SKILL.md)\n\n## Status\n\nThe current implementation provides:\n\n- official `@modelcontextprotocol/sdk` stdio server\n- Chrome and Microsoft Edge Native Messaging host mode\n- install/uninstall commands with manifest backup\n- JSON-RPC bridge socket under `/tmp/codex-browser-use`\n- Chrome tab, navigation, screenshot, CDP, and event MCP tools\n- bundled skill documentation for Agent tool ordering\n\n## Platform Support\n\n| Platform | Status | Notes |\n| --- | --- | --- |\n| macOS | Tested | Primary supported platform. |\n| Linux | Experimental | Manifest path targets Google Chrome under `~/.config/google-chrome`. |\n| Windows | Unsupported | Native Messaging registration uses registry keys on Windows and is not implemented yet. |\n\nNode.js 20 or newer is required. npm Trusted Publishing for releases uses Node.js 24 in GitHub Actions.\n\n## Browser Support\n\nBoth Chromium browsers use the same Codex extension and the same `chrome-extension://` origin, so a single manifest works for either.\n\n| Browser | Status | Notes |\n| --- | --- | --- |\n| Google Chrome | Tested | Default target. |\n| Microsoft Edge | Supported | Same extension and native-messaging mechanism; installs to the Edge `NativeMessagingHosts` directory. |\n\nCommands accept `--browser \u003cchrome\\|edge\\|all\u003e`. Without the flag, `install-native-host` installs for every supported browser whose profile directory exists, `uninstall-native-host` targets every browser it previously installed for, and `status` reports both.\n\n## Quick Start\n\nInstall and enable the [Codex Chrome Extension](https://chromewebstore.google.com/detail/hehggadaopoacecdllhhajmbjkdcmajg) in the Chrome or Edge profile you want to automate.\n\nInstall the native host (auto-detects the browsers present):\n\n```bash\nnpx -y codex-control-chrome-mcp@latest install-native-host\n```\n\nTo target one browser explicitly:\n\n```bash\nnpx -y codex-control-chrome-mcp@latest install-native-host --browser edge\n```\n\nConfigure your Agent to use the MCP stdio server:\n\n```json\n{\n  \"type\": \"stdio\",\n  \"command\": \"npx\",\n  \"args\": [\"-y\", \"codex-control-chrome-mcp@latest\", \"--stdio\"],\n  \"startup_timeout_sec\": 30\n}\n```\n\nCheck status:\n\n```bash\nnpx -y codex-control-chrome-mcp@latest status\n```\n\nUninstall and restore the previous Codex native host manifest:\n\n```bash\nnpx -y codex-control-chrome-mcp@latest uninstall-native-host\n```\n\n## Agent Skill\n\nIf your Agent supports skills, install or reference the bundled skill folder:\n\n```text\nskills/codex-control-chrome-mcp\n```\n\nThe skill documents the recommended MCP tool order for:\n\n- status checks\n- tab listing and claiming\n- CDP attach and command execution\n- screenshots\n- network and console event reads\n- tab finalization\n\n## Security Notes\n\nThis project controls the user's normal Chrome profile. MCP clients connected to it can inspect page contents and send raw CDP commands to claimed tabs.\n\nOnly install and run it on machines and Chrome profiles you own or are explicitly authorized to automate. Do not send browser cookies, password stores, profile databases, tokens, or private session files in issues or logs.\n\nSee [SECURITY.md](./SECURITY.md) for the security model and reporting process.\n\n## How It Works\n\nThe Codex Chrome Extension does not need an external Chrome remote debugging port. It uses Chrome Native Messaging and the extension's `chrome.debugger` permission:\n\n```text\nChrome extension\n  -\u003e chrome.runtime.connectNative(\"com.openai.codexextension\")\n  -\u003e codex-control-chrome-mcp native host\n  -\u003e local MCP bridge socket\n  -\u003e chrome.debugger.attach / chrome.debugger.sendCommand\n  -\u003e CDP\n```\n\nBecause the control entrypoint is inside the normal Chrome profile, existing cookies, logged-in sessions, tabs, and extensions can be reused.\n\nRead more:\n\n- [Architecture](./docs/architecture.md)\n- [Install And Uninstall](./docs/install.md)\n- [Official Socket Probe Notes](./docs/socket-probe.md)\n- [Release Process](./docs/release.md)\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm ci\n```\n\nRun checks:\n\n```bash\nnpm run ci\n```\n\nRun the MCP server locally:\n\n```bash\nnode ./bin/codex-control-chrome-mcp.js --stdio\n```\n\nRun native host mode locally for development:\n\n```bash\nnode ./bin/codex-control-chrome-mcp.js --native-host\n```\n\n## Troubleshooting\n\n`status` reports, per browser (under `install.chrome` / `install.edge`), a `registered` flag and a `classification` of the live manifest. When `registered` is `false` and `classification.kind` is `official-openai`, a Codex update has reclaimed that browser's manifest (see below). `classification` identifies OpenAI's genuine host by stable signals — the `com.openai.codexextension` name, the official extension origin, the bundle path, the binary format, and (on macOS) the OpenAI code signature — not by filename.\n\n### A Codex update stopped the bridge\n\nCodex App/extension updates re-register their own `com.openai.codexextension` native-messaging manifest, which overwrites this project's proxy registration (the bundled host binary has even been renamed across releases). The symptom is `status` showing `sockets: []`, `registered: false`, and a manifest `path` back inside the Codex bundle.\n\nThe MCP stdio server now **self-heals**: on startup it re-asserts the manifest when it detects it was reverted, so you usually do not need to re-run `install-native-host`. Because Chrome only reads the manifest when the extension reconnects, **reload the Codex Chrome Extension (or restart Chrome) once** after a Codex update to bring the bridge back. Set `CODEX_CONTROL_CHROME_NO_AUTO_REGISTER=1` to disable the auto re-register.\n\nIf `status` shows no bridge sockets, reload Chrome or the Codex Chrome Extension after installing the native host.\n\nIf Codex App integration stops working, uninstall this native host to restore the backed-up manifest:\n\n```bash\nnpx -y codex-control-chrome-mcp@latest uninstall-native-host\n```\n\nIf tab or CDP tools fail, use the bundled skill workflow: list tabs again, claim only current tab IDs, attach before raw CDP calls, and read CDP events after enabling the relevant domain.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiola1999%2Fcodex-control-chrome-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiola1999%2Fcodex-control-chrome-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiola1999%2Fcodex-control-chrome-mcp/lists"}