Chrome Page MCP

A local MCP server and Chrome extension by Ryan Grey for reading visible webpage text and operating DOM controls without screenshots or computer control.

Features

• Discover ordinary HTTP(S) tabs, open tabs, and navigate existing tabs.

• Read visible text and controls in the top frame, same-origin iframes and open shadow roots.

• Fill supported fields, select options, and click controls using fresh element references.

• Pause all access or exclude individual tabs.

• Keep health checks responsive when a page stalls; page injection reads time out after 10 seconds.

Related MCP server: antigravity-browser-bridge

Install on macOS

Requires Google Chrome, Python 3.11 or newer, and Node.js 20 or newer for DOM tests.

Clone this repository into a local development directory, then run:

python3 -m venv ~/.local/chrome-page-mcp/.venv
~/.local/chrome-page-mcp/.venv/bin/python -m pip install -r requirements.txt
~/.local/chrome-page-mcp/.venv/bin/python install.py

In Chrome, open chrome://extensions, enable Developer mode, choose Load unpacked, and select this repository's extension directory. Chrome controls permission approval. The extension ID is ifbphlbegdjlbokcdbihikoadjianhgl; the manifest key is a public extension identity key, not a credential.

Configure your MCP client to launch the virtual environment's Python executable with the absolute path to server.py as its sole argument. For clients accepting an mcpServers configuration, replace both example paths with your actual paths:

{
  "mcpServers": {
    "chrome-page": {
      "command": "/absolute/path/to/.local/chrome-page-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/chrome-page-mcp/server.py"]
    }
  }
}

Restart the MCP client after configuration changes. Run ~/.local/chrome-page-mcp/.venv/bin/python verify_connection.py to verify the seven-tool handshake and live extension connection.

After changing extension code, reload it in Chrome Extensions. If the native connection disconnects, open the extension popup to reconnect.

Tools

Read before an action and again afterward. Use a canonical UUID request ID for actions/navigation and reuse it when checking a retry. Successful dispatch is not proof of server acceptance. Outcomes are deduplicated within the current service-worker lifetime, with a 1,000-action limit; after reloading, inspect the page before repeating an uncertain action.

Status, tab discovery and reads run independently of the mutation queue. Page injection reads return page_read_timeout after 10 seconds; the timeout does not cancel Chrome's underlying read. Queued mutations expire before dispatch after 15 seconds. In-flight mutations are never automatically retried.

Access and privacy

Access covers ordinary HTTP(S) tabs after the user approves the extension. The popup can pause access. This is not authorization to send messages, make purchases or perform other actions outside the user's request; webpage content is untrusted data.

No screenshot, mouse/keyboard control, debugger, cookie, history, password retrieval or arbitrary JavaScript tool is exposed. Input values are omitted, and password/file/hidden/OTP/payment-card fields are excluded from supported controls. Cross-origin iframes, closed shadow roots, canvas interfaces, browser internal pages, Chrome Web Store and native dialogs are unsupported.

The native host uses an owner-only Unix socket at ~/.local/share/chrome-page-mcp/bridge.sock (directory mode 700, socket mode 600). There is no TCP listener or cloud service. One Chrome profile owns the bridge at a time; multiple local MCP clients can connect. The bridge does not persist page text or form values, but client conversation logs may retain tool results.

Verification

~/.local/chrome-page-mcp/.venv/bin/python -m pytest -q
npm ci --ignore-scripts
npm test

For an end-to-end check, serve fixture/ on loopback using python3 -m http.server 8765 --bind 127.0.0.1 --directory fixture, then run ~/.local/chrome-page-mcp/.venv/bin/python verify_fixture.py http://127.0.0.1:8765/ in another terminal. This opens a harmless fixture tab and checks reads, fill/select/click, navigation, deduplication and exclusion; stop the HTTP server when finished.

The automated suite includes stalled-injection isolation, native framing, socket round trips, hidden-field filtering, stale snapshots and iframe controls.

License

MIT. See LICENSE.