# chrome-web-mcp

[日本語版 README](README.jp.md)

> **Supported OS: Linux only.** Windows and macOS are not supported. Using
> Docker does not change the host OS support policy.

> [!CAUTION]
> Single-session use only: one client process, one browser, sequential searches.
>
> - Normal use never trips the limiter: `pace_warning` fires only at 15+
>   searches per minute. Sequential or lightly-parallel use stays far below it.
> - A warning is advisory, not a block: searches keep running. But Google
>   counts total volume too — sustained barrages end in CAPTCHA regardless of
>   pacing (observed after dozens of searches in one session). When challenged:
>   wait a few minutes and retry in headless (`xvfb`) mode — it usually clears
>   by itself; in visible (`xephyr`) mode, solve the challenge in the
>   `chrome-web-mcp` window yourself, then retry. `last_captcha_at` in
>   `health_check` shows the last hit.
> - opencode + subagents: SAFE. All agents share one server process and one
>   browser. Concurrent searches are pooled in a shared query queue
>   (per-process lock + SQLite pacing) and executed sequentially — verified
>   with 3 simultaneous subagents and 35 rapid searches, no CAPTCHA.
> - Separate processes at once are NOT absorbed: each process spawns its OWN
>   browser, so parallel CLIs look like fresh users hitting Google together.
>   Each one can be CAPTCHA-challenged independently (observed). Stagger starts
>   by seconds or raise `CW_MIN_DELAY` / `CW_MAX_DELAY`.

A stdio Model Context Protocol server that exposes focused browser tools:

- `google_search` — Google search through a JavaScript-rendered Chrome instance.
- `fetch_url` — JavaScript-rendered readable text extraction for public HTTP(S) URLs.
- `health_check` — display, browser, queue, and CAPTCHA status.

The server is designed to be configured by any MCP client that can launch a
stdio command.

## Features

- JS-rendered Google search + public URL fetch through a real (non-headless)
  Chrome on a private virtual display (Xephyr when visible, Xvfb when hidden)
  — harder to bot-detect than `--headless`.
- Shaped markdown by default (`trafilatura` + `html2text`, pure-Python, no
  extra service), with full-text fallback and follow-up link targets.
- Language/region hints (`hl`/`gl`) for reproducible JA/EN results.
- Parallel-safe: concurrent searches and fetches serialize only where the
  browser lifecycle requires it; each fetch uses its own tab.
- Fail-closed fetching: private networks, metadata hosts, and
  credential-bearing URLs are blocked, including post-redirect targets.
- Shared SQLite pacing for Google searches across MCP processes.
- `health_check` for display/browser/queue/CAPTCHA observability.
- Linux only (Xvfb/Xephyr, `fcntl`, process groups).

## Requirements

- Python 3.10 or newer
- Google Chrome, Google Chrome for Testing, or Chromium
- `Xephyr` on Linux for the default visible-window mode
- `Xvfb` on Linux for hidden-window mode
- `xpra` on Linux if interactive CAPTCHA recovery is desired

The Python dependencies are installed with the package. Chrome and Xvfb remain
host prerequisites because they are external browser processes.

Non-headless Chrome on Xvfb is intentional: `--headless` is easier to
bot-detect, so Xvfb is kept as a requirement even though it is heavier.

## Platform support

Linux only. Windows and macOS are not supported: this server depends on
`Xvfb`/`Xephyr`, Chromium with `--ozone-platform=x11`, `fcntl.flock`, and
process-group signaling (`killpg`), none of which work as-is on Windows.
A Windows/macOS port would need headless Chrome plus a different locking
scheme. Docker helps only on a Linux host with an X server for `xephyr` mode.

## Headless environments

On a headless server, CI runner, SSH session without X forwarding, or any
machine without a desktop display, set `show_browser` to `false`:

```json
{
  "show_browser": false
}
```

Edit `~/.config/chrome-web-mcp/config.json` (or the file specified by
`CW_CONFIG`) and restart the MCP client. This forces Chrome onto hidden Xvfb
and avoids the Xephyr startup error caused by the lack of a user `DISPLAY`.

The built-in default is `true` for desktop use, so do not omit this setting on
a headless machine. A Docker installation already sets
`CW_DISPLAY_MODE=xvfb` inside the container, so it normally needs no host
display or extra setting.

## Linux quickstart (Debian/Ubuntu, copy-paste)

```bash
# 1. System dependencies
sudo apt update && sudo apt install -y chromium xvfb xserver-xephyr x11-utils python3-venv
which chromium || which google-chrome || which chromium-browser
which Xvfb
python3 --version  # 3.10+

# 2. Create an environment and install the package (either one)
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install -e '.'
# or: python -m pip install chrome_web_mcp-0.2.0-py3-none-any.whl
```

MCP handshake check (`TOOLS: ['fetch_url', 'google_search', 'health_check']` expected):

```bash
uv run python -c "
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def main():
    params = StdioServerParameters(command='uv', args=['run','--directory','/absolute/path/to/chrome-web-mcp','chrome-web-mcp'])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            print('TOOLS:', [t.name for t in (await session.list_tools()).tools])
asyncio.run(main())
"
```

opencode (`~/.config/opencode/opencode.json`, Linux path example):

```json
{
  "mcp": {
    "chrome-web": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/home/user/projects/chrome-web-mcp", "chrome-web-mcp"],
      "enabled": true
    }
  }
}
```

Notes:

- Replace `/absolute/path/to/chrome-web-mcp` with your checkout path.
- `CW_CHROME=/usr/bin/chromium` only if auto-detection misses your binary.
- Concurrent calls within one server are supported. Searches are serialized;
  fetches use independent tabs and share a serialized browser startup.
- `xephyr` mode needs a real desktop `DISPLAY` plus `xserver-xephyr`;
  on a headless host or over SSH without X forwarding it will not start.
  Default `xvfb` mode needs no `DISPLAY`.

## Install and run

From a built wheel:

```bash
python -m pip install chrome_web_mcp-0.2.0-py3-none-any.whl
chrome-web-mcp
```

For a published package, an MCP client can let `uvx` install it on demand:

```json
{
  "mcpServers": {
    "chrome-web": {
      "command": "uvx",
      "args": ["--from", "chrome-web-mcp==0.2.0", "chrome-web-mcp"]
    }
  }
}
```

For a local checkout:

```json
{
  "mcpServers": {
    "chrome-web": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/chrome-web-mcp", "chrome-web-mcp"]
    }
  }
}
```

The same server can be registered in Hermes with YAML:

```yaml
mcp_servers:
  chrome-web:
    command: /absolute/path/to/python
    args:
      - -m
      - chrome_web_mcp
    timeout: 120
    connect_timeout: 60
    enabled: true
```

For a wheel installation, use the Python interpreter from the environment
where the wheel was installed. MCP clients should launch the process over
stdio and must not add shell-specific quoting around the arguments.

## Docker

The image bundles Python, dependencies, Chromium, Xvfb (plus Xephyr/xdotool
for visible-window mode), so users only need Docker:

```bash
docker build -t chrome-web-mcp .
```

```json
{
  "mcpServers": {
    "chrome-web": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chrome-web-mcp"]
    }
  }
}
```

For opencode, add a separate entry to `~/.config/opencode/opencode.json` so
you can keep the local and Docker versions available side by side:

```json
"chrome-web-docker": {
  "type": "local",
  "command": ["docker", "run", "--rm", "-i", "chrome-web-mcp:latest"],
  "enabled": true,
  "timeout": 120000
}
```

The Docker image uses hidden Xvfb by default. This is separate from the local
`chrome-web` entry, whose `show_browser` setting can display a desktop window.
Restart opencode after adding or changing the entry.

Hidden mode is normally sufficient. If Google returns
`captcha_required: true`, the CAPTCHA is displayed inside the Docker
container's browser, so the local `chrome-web` window cannot solve it. Start
the Docker MCP server in visible Xephyr mode instead and retry the search:

```bash
docker run -i --rm \
  -e DISPLAY=$DISPLAY \
  -e CW_DISPLAY_MODE=xephyr \
  -e XAUTHORITY=$XAUTHORITY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v "$XAUTHORITY":"$XAUTHORITY":ro \
  chrome-web-mcp
```

This requires a Linux desktop X display and `Xephyr`. On Wayland/Mutter, the
working Xauthority file may be a `.mutter-Xwaylandauth.*` file under
`$XDG_RUNTIME_DIR` rather than `$XAUTHORITY`; mount that directory and set
`XAUTHORITY` to the matching path inside the container. The resulting
`chrome-web-mcp` window belongs to the Docker process, and you must retry using
that same Docker MCP session. For the simplest CAPTCHA recovery, use the local
`chrome-web` entry with `show_browser: true` from the beginning.

Image size is about 1.5 GB (mostly Chromium and fonts).

## Update

For a local checkout, pull and re-sync (restart the MCP client afterwards):

```bash
git -C /absolute/path/to/chrome-web-mcp fetch origin
git -C /absolute/path/to/chrome-web-mcp reset --hard origin/main
```

`reset --hard` is used instead of `pull --ff-only` because history is
occasionally force-pushed; stash local changes first if you have any
(`git stash`). `uv run --directory ... chrome-web-mcp` picks up the new
dependencies automatically on next launch — no reinstall step needed.

For a dedicated venv (e.g. `~/.local/share/chrome-web-mcp/venv`), reinstall
after pulling:

```bash
uv pip install --python ~/.local/share/chrome-web-mcp/venv/bin/python -U -e /absolute/path/to/chrome-web-mcp
```

For a wheel install, rebuild and reinstall:

```bash
python -m build --wheel --outdir /absolute/path/to/chrome-web-mcp/dist /absolute/path/to/chrome-web-mcp
python -m pip install -U /absolute/path/to/chrome-web-mcp/dist/chrome_web_mcp-*.whl
```

For Docker, just rebuild — no `Dockerfile` edit is needed (it copies
`pyproject.toml` + `src/` and runs `pip install .`, so code and dependency
changes are picked up automatically):

```bash
docker build -t chrome-web-mcp /absolute/path/to/chrome-web-mcp
```

Verify after update:

```bash
uv pip list --python ~/.local/share/chrome-web-mcp/venv/bin/python | grep -E "chrome-web|trafilatura"
```

## Install size (rough, Debian host)

- Python environment (`.venv`, incl. trafilatura/html2text): ~100 MB
- This package source: under 1 MB
- Chromium set: ~485 MB
- Xvfb + x11-utils: ~5 MB
- Total: ~600 MB, dominated by Chromium. No new system packages were added
  for markdown shaping (pure-Python dependencies only).

## Tools

Workflow: first `google_search`, then `fetch_url` on interesting result URLs
for full text. `health_check` reports server state without starting a browser.

### `google_search`

Input:

```json
{"query": "search terms", "limit": 5, "hl": "ja", "gl": "jp"}
```

`limit` is an integer from 1 to 20. Results are returned as structured JSON
with `title`, `url`, `description`, and `position` fields, plus `waited_ms`
(the shared rate-limiter queue wait). `hl`/`gl` are optional Google language
(`ja`/`en`) and region (`jp`/`us`) hints; defaults preserve Japanese results.
`query` is required, max 512 chars. Searches run one at a time per process
and are paced across processes (see Runtime configuration). Bursts of 15+
searches per minute return a `pace_warning` — slow down or batch queries to
avoid a Google CAPTCHA; `health_check` reports the recent count.

### `fetch_url`

Input:

```json
{"url": "https://example.com", "char_limit": 15000, "format": "markdown"}
```

Only public `http://` and `https://` URLs without embedded credentials are
accepted. Localhost, private IP ranges, metadata hosts, and non-public DNS
resolutions are rejected. A mandatory local HTTP proxy validates every upstream
connection and connects to the validated numeric address, including redirects,
subresources, WebSockets, and DNS changes. Chrome's loopback proxy bypass, QUIC,
and non-proxied WebRTC UDP are disabled. IPv6 translation/tunneling addresses
(NAT64, 6to4, Teredo) are also rejected. `char_limit` is an integer from 100 to
200000. HTML/text snapshots are read in chunks, with a 16Mi-character extraction
limit independent of the returned text limit. Text is cut at a
sentence boundary when possible. Returns `requested_url`, `final_url`,
`redirected`, `total_chars`, and `truncated` alongside `title` and content
(`url` mirrors `final_url` for compatibility). `format` defaults to
`markdown`: shaped readable markdown with boilerplate removed
(`trafilatura`, `html2text` fallback). The response reports `formatted: true`
and the `extraction` method, so agents can tell it was shaped — if content
looks missing, retry with `format: "text"` for the full rendered text.
`format: "links"` adds follow-up link targets. Concurrent fetches are
parallel-safe; each uses its own tab. `url` is required, max 2048 chars.
Failures return `{"success": false, "error": "..."}` (plus
`"captcha_required": true` for Google challenges). This shaping reuses the same
`trafilatura` + `html2text` approach as a self-hosted jina-compatible Reader,
without needing the extra service.

### `health_check`

Input: `{}` (no arguments).

Returns `display_mode`, browser/process liveness, the rate-limiter queue wait,
its `min`/`max` delays, and the last CAPTCHA time.

## Runtime configuration

Most users only need the JSON file:

```bash
mkdir -p ~/.config/chrome-web-mcp
cp examples/config.json examples/config.md ~/.config/chrome-web-mcp/
```

Then edit `~/.config/chrome-web-mcp/config.json` and restart the MCP client.
The settings most people change are:

```json
{
  "show_browser": true,
  "hl": "ja",
  "gl": "jp"
}
```

- `show_browser`: `true` shows the browser window; `false` hides it.
- `hl`: Google interface language. `ja` is Japanese and `en` is English.
- `gl`: Google result region. `jp` is Japan and `us` is the United States.

The built-in search defaults are `hl: ja` and `gl: jp`, but each user can set
their own values in this file. For example, use `"hl": "en"` and
`"gl": "us"` for English/US-oriented Google results. See
[`examples/config.md`](examples/config.md) for all settings and examples.

The JSON file is optional. If it is absent, the built-in defaults are used and
the browser window is shown (`show_browser: true`). Set it to `false` to hide
the window. JSON comments are not supported, so keep `config.json` as plain
JSON.

Optional environment variables:

- `CW_CONFIG` — path to an optional JSON config file for window on/off and
  tool defaults. When unset, `~/.config/chrome-web-mcp/config.json` is used
  if it exists. Explicit environment variables below win over the file.
  Settings become tool defaults when the caller omits them. Unknown keys warn
  on stderr; invalid values warn and keep the built-in default per key.
- `CW_CHROME` — explicit Chrome/Chromium executable path.
- `CW_PROFILE_DIR` — explicit browser profile directory. By default, each
  server process uses an isolated per-PID temporary profile.
- `CW_LOCK_PATH` — explicit lock-file path when `CW_PROFILE_DIR` is set.
- `CW_RATE_LIMIT_DB` — shared SQLite path for the Google-search start-slot
  queue. By default it is `/tmp/chrome-web-mcp/search-rate-limit.sqlite3`, so
  separate MCP processes of the same user share one limiter.
- `CW_MIN_DELAY` / `CW_MAX_DELAY` — randomized gap (seconds) between Google
  search starts. Defaults `1.0` / `2.5`.
- `CW_DISPLAY_MODE` — advanced environment override for `show_browser`:
  `xvfb` runs Chrome on a private, fully hidden display, while `xephyr` runs
  Chrome inside a nested `Xephyr` window titled `chrome-web-mcp` on your
  desktop. The latter is visible, minimizable, and movable, but tool calls can
  never pop a window to the front outside of it. Requires `Xephyr`
  (`xserver-xephyr`) and a user `DISPLAY`.
- When `CW_DISPLAY_MODE=xephyr`, the server preserves an explicit `XAUTHORITY`
  or automatically discovers Mutter's `.mutter-Xwaylandauth.*` file under
  `XDG_RUNTIME_DIR`, then falls back to `~/.Xauthority`. This lets stdio MCP
  clients that filter their inherited environment still connect to the user's
  Xwayland display.
- `CW_XPRA_EXPOSE` — set to `1` to re-enable automatic Xpra attach when a
  CAPTCHA appears. Off by default: automatic attach once crashed the desktop
  session, so the server only reports the CAPTCHA and leaves the browser
  where it is.

The default per-process profile prevents separate MCP clients from contending
for one Chrome profile. Do not share a profile between live server processes
unless that is intentional.

Google-search calls also reserve a slot in the shared SQLite queue. Separate
MCP processes therefore start searches one at a time with a 1.0–2.5 second
randomized gap. A reserved slot is not retried automatically if Google returns
an error; the tool returns the error to the MCP client. `fetch_url` is not put
through this Google-search queue.

## Security and scope

- The server exposes no arbitrary page-context JavaScript tool.
- Browser HTTP(S)/WebSocket connections are restricted to public addresses by
  a local validating proxy; private destinations are rejected before connecting.
  Input URLs also reject embedded credentials and recognizable secret patterns.
  This does not classify every possible secret in arbitrary page URLs/content.
- Each server owns and cleans up its Chrome and Xvfb process groups.
- Chrome is explicitly forced onto the private X11/Xvfb display, even when the
  host desktop session uses Wayland; the user desktop should not be surfaced.
- SIGTERM and SIGINT trigger browser and temporary-profile cleanup before exit.
  Startup recovers recorded Chrome/display processes using PID and start time,
  not broad process-name matching. Legacy profiles without process records can
  recover Chrome by exact profile argument; their Xvfb cannot be safely identified.
- Google result URLs are normalized and deduplicated before returning.

This package does not bypass authentication or CAPTCHA challenges. It is a
browser-backed search/fetch MCP server, not a general remote browser-control
API.

When Google presents a CAPTCHA during `google_search`, the server returns
`captcha_required: true`. With `show_browser: true` (Xephyr), solve the
challenge in the `chrome-web-mcp` window on your desktop, then retry the same
search. With `show_browser: false` (Xvfb), wait a while and retry. Automatic
Xpra attach is disabled unless `CW_XPRA_EXPOSE=1` is set, because it once
crashed the desktop session.

## Acknowledgements

Browser-backed web tooling was originally derived from
[antirez/ds4](https://github.com/antirez/ds4) and subsequently substantially
reworked for MCP. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the
applicable MIT license notice.

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test (`pytest -q -m 'not live'` for deterministic only), and build steps.