Content
# 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.
Connection Info
You Might Also Like
No recommendations available