Julian Chrome Controller

A macOS Chrome extension, Native Messaging host, CLI, and MCP server for working with your existing Chrome profile. Read authorized task pages and act on fresh snapshots without moving your login data.

中文说明 · Contributing · Security

Source available for noncommercial use. PolyForm Noncommercial 1.0.0 is not an OSI-approved open-source license. This release grants no commercial-use license, including business internal operations, commercial services/products, or resale; obtain a separate rights grant for such use. The standard license explicitly permits use by the organizations listed in its Noncommercial Organizations clause. The full license controls. Preserve NOTICE when redistributing. Copyright 2026 Julian Cooper.

Features and requirements

• List existing tabs, claim task tabs, and open authorized URLs in background tabs.

• Read visible text and targets in the top document and open Shadow DOM.

• Click, fill ordinary fields, select native options, and scroll using snapshot IDs.

• Track session ownership, safeguard closing, reconnect locally, and report uncertain outcomes.

Requires macOS, Node.js 22+, npm, Git, Chrome 120+, and trusted local/MCP callers. Use a short stable checkout: the UTF-8 byte length of <checkout>/runtime/control.sock must be less than 100. There is no HTTP port, API key, or .env file.

Related MCP server: Chrome Live MCP

Quick start

mkdir -p ~/Projects
git clone https://github.com/Cooperiano/julian-chrome-controller.git ~/Projects/jcc
cd ~/Projects/jcc
./setup.sh

Default setup runs npm ci --ignore-scripts and prepares local configuration; it does not register a host with Chrome. Generated absolute-path configuration and runtime files are deliberately excluded from Git. To register this checkout:

./setup.sh --install

The installer refuses to overwrite registration pointing at another checkout. Preserve the existing installation and explicitly plan migration before changing it; do not delete the host to bypass this check. Moving this checkout requires regenerating local configuration and reviewing registration.

Open chrome://extensions in the intended profile, enable Developer mode, choose Load unpacked, and select the checkout's extension directory. Open the popup to check the connection. Load this extension in only one profile at a time.

The retained public key fixes extension ID mmmkdojcghbmcbghbblndhlcmjfonkgd; it is not a private signing key. Permissions are tabs, scripting, nativeMessaging, storage, alarms, and HTTP/HTTPS host access, for tab/page operations, local transport, ownership state, and connection maintenance. Incognito is disabled.

Using with Codex

AGENTS.md provides development context. Inspect the generated codex-mcp.toml and merge its [mcp_servers.julian_chrome] block into your Codex configuration, preserving unrelated settings. Other stdio MCP clients can launch node with the absolute path to src/mcp.mjs.

There are 12 chrome_* tools. Each MCP process owns a session lease; exit releases claims and keeps tabs open. Tool availability in running clients depends on their configuration reload behavior. Verify a real connection by listing existing tabs and snapshotting an authorized task page. health.version and snapshot.engineVersion should be 0.2.0. Popup status and mock tests alone do not prove live Chrome readiness.

CLI and operation rules

node src/cli.mjs --help
node src/cli.mjs health
node src/cli.mjs tabs.list

Replace example 123 with a real authorized tab ID:

node src/cli.mjs tabs.claim '{"tabId":123}' task-session-001
node src/cli.mjs page.snapshot '{"tabId":123}' task-session-001
node src/cli.mjs tabs.release '{"tabId":123}' task-session-001

Use distinct session names per task, reuse them within a CLI task, and release claims when finished. Navigation/closing require the current expectedUrl; page actions require a fresh snapshot, and clicks/fills/selections require its target ID. dispatched means a DOM action was dispatched: read the page again to verify the result.

After timeout/disconnect, an action may have happened and its outcome may be unknown. Inspect the page before deciding what to do; never automatically repeat a mutation. Claims do not authorize purchases, publishing, messages, or other external effects.

Limits and troubleshooting

Unsupported: iframe content, closed Shadow DOM, screenshots, file upload, native dialogs, and sites requiring trusted user-input events. Sensitive-field heuristics omit detected values and reject filling passwords, credentials, verification codes, and payment fields. They are not exhaustive redaction; ordinary text, URLs, titles, and fields can contain private data. Same-UID local processes and MCP clients are trusted; see SECURITY.md.

For CHROME_NOT_CONNECTED, check registration, extension activation, profile, and checkout path. Reload the extension after source updates and read back both versions. The popup's reconnect control refreshes transport while keeping existing tabs. Pause access by disabling the extension in Chrome. No automatic upload or telemetry is implemented; your MCP client may process or retain returned data under its own policies.

Development and references

npm ci --ignore-scripts
npm test
node src/install.mjs --prepare-only

There is no build step or lint script. Runtime code uses Node built-ins; tests use jsdom and simulated browser components to cover protocol, broker, Native Messaging, MCP, controller, popup, page actions, and installation. Passing tests does not replace live Chrome acceptance.

browser-bridge was an architectural reference for the existing-profile extension/native-host split; no code was copied. See official Chrome Native Messaging and service worker lifecycle documentation. Third-party dependencies retain their licenses, including the MIT-licensed jsdom development dependency.