Zen Browser MCP

MCP server for browser automation with Playwright and browser-use.

What is it?

Zen Browser MCP is an MCP server that exposes a headless Chromium browser over HTTP/SSE. It combines direct Playwright-style tools for deterministic browser steps with a browser-use agent flow for higher-level multi-step tasks.

It is built to run from Docker first, with browser artifacts written through a controlled /data volume.

Why?

Browser automation is useful when a website does not expose a clean API, but running an agent browser directly on your host machine increases the blast radius. Zen Browser MCP keeps the browser runtime in a container and persists only the files you explicitly bind through ${DATA_PATH}/browser-mcp:/data.

Docker isolation reduces host exposure, but it is not a complete data-loss prevention system. Treat credentials, downloads, screenshots, and visited pages with the same care you would in any automation workflow.

Quick Start

Copy the example environment file:

cp .env.example .env

Set your provider, model, port, and data path:

OPENAI_API_KEY=your-provider-key
OPENAI_BASE_URL=https://your-provider.example/v1
MODEL_NAME=gpt-5.4-mini
BROWSER_MCP_TAG=latest
BROWSER_MCP_PORT=8000
DATA_PATH=./data

Start the MCP server:

docker compose up

The compose file runs zen-mcp/browser:${BROWSER_MCP_TAG}, maps ${BROWSER_MCP_PORT}:8000, and persists runtime files through ${DATA_PATH}/browser-mcp:/data.

See the configuration docs for the full environment reference.

What can it do?

• Navigate pages, scroll, wait for selectors or text, and inspect visible text.
• Click elements, type into inputs, and press keyboard keys.
• Capture full-page or element screenshots as artifacts.
• List and retrieve files from the runtime data directory.
• Run complex browser tasks with a browser-use agent instruction.
• Use any OpenAI-compatible provider through OPENAI_BASE_URL.

Docs

Full documentation is available at zenkiet.github.io/browser-mcp.

Contribute

Clone the repo and install Python dependencies:

git clone https://github.com/zen-mcp/browser.git
cd browser
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the validation checks:

python3 -m compileall -q src tests main.py
python3 -m unittest discover -s tests -p "test_*.py"
docker build -t browser-mcp:ci .

For documentation changes:

cd docs
yarn install --frozen-lockfile
yarn build

Open a pull request with a focused change and the checks you ran.

License

Licensed under the Apache License 2.0.

Star me if Zen Browser MCP helps your agents browse with less risk.