Skip to main content
Glama

JevBrow

Pre-alpha 0.1 · Local browser tools for Codex, backed by your own Brave or Chrome session.

JevBrow connects to a browser through the Chrome DevTools Protocol (CDP) and exposes a small set of MCP tools. Codex reads the visible page, chooses an action from JevBrow's observed list, and receives a new observation after each action. The MCP server does not call a second model or require a model API key.

This is an early release. It handles common HTML controls and still needs supervision on consequential actions.

What it does

  • Opens a background tab owned by JevBrow in a browser that is already running locally.

  • Reports visible text, supported controls, action IDs, and a page fingerprint.

  • Clicks, types, selects a native option, scrolls, or waits only through an action ID from the latest observation.

  • Refuses stale actions and consumes an observation before browser input, so a failed mutation is never replayed blindly.

  • Closes its own tab without closing your other tabs or browser process.

Page text and labels are untrusted website content. The MCP client sees that content to decide what to do. Websites you open may be remote services, even though the browser connection and MCP process run locally.

Related MCP server: chrome-devtools-mcp

Requirements

  • Python 3.12 or newer and uv

  • Brave or Chrome with remote debugging available at http://127.0.0.1:9222

  • An MCP client such as Codex

Use a browser profile you intend to automate. CDP can interact with pages and sessions in that profile; keep the debugging port bound to loopback and do not expose it to your network.

Install for Codex

git clone https://github.com/ZnOw01/JevBrow.git
cd JevBrow
uv sync
python scripts/codex_config.py install

The installer adds a marked jevbrow block to ~/.codex/config.toml, using the actual checkout path, and keeps recovery snapshots alongside that file. It leaves unrelated settings in place. Restart Codex so it discovers the new MCP server. If your CDP port differs, change BU_CDP_URL in the marked block to your loopback endpoint.

To remove the integration:

python scripts/codex_config.py uninstall

You can also add the MCP server manually:

[mcp_servers.jevbrow]
command = "uv"
args = ["run", "--directory", "/absolute/path/to/JevBrow", "jevbrow"]
startup_timeout_sec = 30

[mcp_servers.jevbrow.env]
BU_CDP_URL = "http://127.0.0.1:9222"

MCP workflow

  1. Call jevbrow_open(url) for an http or https page, or jevbrow_observe() for the existing JevBrow tab.

  2. Choose an action_id from the returned actions and pass its fingerprint to jevbrow_click, jevbrow_type_text, jevbrow_select, or jevbrow_scroll_or_wait.

  3. Inspect the observation returned by that tool before another action. After an error or stale fingerprint, observe again.

  4. Call jevbrow_close() when finished.

The API accepts no model-generated selectors, JavaScript, shell commands, or coordinates. Text entry is limited to an observed editable field and does not submit the form by itself. JevBrow exposes at most 250 page actions per observation and reports how many were omitted.

Optional standalone mode

The original autonomous runner is separate from MCP. It uses a local OpenAI-compatible model endpoint (for example, CLIPRox) to choose actions and write field values. MCP mode never reads these model credentials.

cp .env.example .env
# Fill in JEVBROW_MODEL_API_KEY and adjust the local endpoint if needed.
uv run --env-file .env jevbrow-run --url https://example.com --goal 'Describe the page.'

For the local inspector, run uv run --env-file .env jevbrow-demo and open the loopback URL it prints. .env, browser recordings, caches, and local agent settings are ignored by Git.

Development

uv sync --group dev
uv run pytest -q
uv run ruff check .
uv run python scripts/check_guards.py

The first two checks run offline. check_guards.py uses your local CDP browser and a temporary JevBrow-owned tab; it makes no model calls.

Scope and provenance

This project keeps the original jev_ultrafast Python package name. It derives from the MIT-licensed browser-use/jev-ultrafast prototype; the original copyright notice is preserved in LICENSE. The MCP integration and local Codex setup are the focus of this fork.

JevBrow supports common visible HTML and ARIA controls. Shadow roots, frames, canvas controls, uploads, pop-ups, nested scrolling, and complex keyboard widgets can block progress. A visible action can still be the wrong action for a task. The older performance reports and demo document the upstream TypeSafe-based prototype; they are historical evidence, not benchmarks of this pre-alpha MCP integration.

Available Tools

7 tools
jevbrow_clickA

Click one observed action with its fingerprint, then inspect the new state.

Inputs: action_id (required), fingerprint (required). Returns: result

jevbrow_closeA
Idempotent

Close only the background tab opened and owned by Jev; does not close the user's other browser tabs.

Inputs: no named parameters. Returns: result

jevbrow_observeA
Read-onlyIdempotent

Read the current URL, visible text, and supported actions before acting.

Inputs: no named parameters. Returns: result

jevbrow_openA

Open an http(s) URL in a Jev-owned background tab in the local browser.

Inputs: url (required). Returns: result

jevbrow_scroll_or_waitA

Execute one observed scroll or wait action by action_id, then return a fresh observation.

Inputs: action_id (required), fingerprint (required). Returns: result

jevbrow_selectA

Select one observed native dropdown option by action_id; never accepts model-generated selectors or values.

Inputs: action_id (required), fingerprint (required). Returns: result

jevbrow_type_textA

Type into one observed field. Inspect the new state before acting again.

Inputs: text (required), action_id (required), fingerprint (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool maps to a distinct browser interaction: open, observe, click, type, select, scroll/wait, and close. Even though scroll_or_wait and observe both return observations, their triggering actions are clearly differentiated and never overlap.

    Naming Consistency5/5

    All tools share a consistent jevbrow_ prefix and use clear imperative verb phrases like open, observe, click, type_text, select, and close. The naming pattern is predictable and easy to reason about as a unified set.

    Tool Count5/5

    Seven tools is well-scoped for a browser automation toolset, covering the full lifecycle from opening a tab to observing state, performing actions, and closing the tab. There is no redundancy or bloated surface area.

    Completeness4/5

    The set covers the essential browser automation loop: open, observe, click, type, select, scroll/wait, and close. Minor gaps like explicit back/forward navigation or refresh are absent, but they are likely accessible through observed clickable actions.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers