Skip to main content
Glama

Jev MCP

中文说明

jev-mcp turns browser-use/jev-ultrafast into one local, session-aware MCP server for fast read-only product research. Jev selects an action and observed target from a DOM snapshot; this wrapper gives an MCP host the tools and lifecycle it needs to use that loop safely.

What it is (and is not)

This is one local stdio MCP server, not a replacement browser extension and not four separate MCPs. It owns browser targets created by Jev and exposes five model-facing tools:

Tool

Use it for

Does not do

jev_browse

Start a public-site search, filtering, or product-detail task

Log in, checkout, pay, upload, or submit an order

jev_status

Read a session's URL, visible text, supported controls, and latest actions

Take another browser action

jev_extract_products

Read visible product card fields: name, price, rating, details, URL

Scroll, click, or guarantee site-specific parsing

jev_stop

Close the Jev-owned Chrome target

Affect ordinary user Chrome tabs

jev_decide

Relay mode: judge host-supplied page state and return the next operation + target element, no browser

Open a browser, session, or tab; take any page action

Relay mode: if you only want Jev as an intermediate decision relay — your own browser tooling (e.g. opencli, computer-use) drives the page and you pass the observed elements in — use jev_decide ONLY. It never opens a browser, session, or tab, so no new pages are created.

The upstream Jev agent remains an isolated Git dependency pinned to commit 1231850a0bf1a0c0341fe408ef1668dbbfdfac46; this repository contains the MCP session layer, output shaping, product extraction, and safety guardrails. This keeps upgrades reviewable and avoids carrying a modified upstream fork.

Related MCP server: browser-research-mcp

Requirements

  • Python 3.12+

  • uv

  • A Chrome/Chromium installation supported by browser-harness

  • An OPENROUTER_API_KEY for Jev Decisions (recommended), or a direct TYPESAFE_API_KEY

  • TEXT_MODEL_API_KEY for search/filter text entry; the default example uses OpenRouter

Setup

git clone https://github.com/wahahaorg/jev-mcp.git
cd jev-mcp
cp .env.example .env
# Put real keys in .env; never commit it. OpenRouter Decisions is the default path.
uv sync
uv run browser-harness --doctor

browser-harness may ask Chrome for remote-debugging permission. The server creates its own background Chrome target; it does not take over the currently visible tab.

Run it locally:

uv run --env-file .env jev-mcp

The server uses stdio: stdout is reserved for MCP JSON-RPC. It waits for an MCP host rather than opening a web page itself.

MCP configuration

Copy the mcpServers.jev-browser object in .mcp.json into your MCP host configuration. Replace the command's directory with this repository's absolute path if the host does not start processes from the repository root.

Example:

{
  "mcpServers": {
    "jev-browser": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/jev-mcp", "--env-file", ".env", "jev-mcp"]
    }
  }
}

Keep credentials in the host environment or .env; never place keys in the configuration committed to source control. The included configuration assumes the host starts it from this repository; use the absolute-path version above otherwise.

Typical flow

  1. Call jev_browse with a public URL and a narrow goal, for example: “Search wireless headphones, set the price filter below $100, and stop when results are visible.”

  2. Keep the returned session_id.

  3. Call jev_status when you need to decide whether the page is ready or why it blocked.

  4. Call jev_extract_products on a visible result/detail page.

  5. Call jev_stop when finished.

When OPENROUTER_API_KEY is present, the wrapper sends Jev decisions to OpenRouter's alpha Decisions endpoint using ~typesafe/jev-latest; otherwise it retains the upstream direct TypeSafe client. The agent is deliberately bounded to 30 browser actions per jev_browse call and upstream Jev itself has a 60-action run cap. Results are observations, not proof of stock, availability, or final checkout price.

Safety model

The wrapper rejects transactional goals before a browser opens and blocks observed add-to-cart, purchase, checkout, payment, upload, credential, card, and verification-code controls just before execution. It also refuses password/file controls inherited from upstream's DOM snapshot safeguards. This is a browsing and extraction integration, not a purchasing bot.

Web content is treated as untrusted data. Product extraction is best-effort and returns only currently visible cards; validate important prices, variants, and shipping details on the source page.

Development and verification

uv run ruff check .
uv run pytest
npx @modelcontextprotocol/inspector uv run --env-file .env jev-mcp

The test suite uses a fake browser/agent, so it does not spend API credits or require Chrome. evals.xml contains ten multi-tool evaluation scenarios, including error recovery and safety boundaries. Use the Inspector with real credentials to validate the MCP framing and a public browsing task.

License

MIT. The upstream Jev dependency is also MIT-licensed; see its repository for its terms and notices.

Available Tools

4 tools
jev_browseA

Start a new browser session and advance a read-only browsing goal.

Use this for finding, filtering, or opening products on a public website. It executes at most max_steps (1–30) before returning a session_id, visible page evidence, and recent actions. Do not use it for login, checkout, payment, uploads, or any task that enters personal or financial data.

Inputs: url (required), goal (required), max_steps.

jev_extract_productsA

Extract product name, price, rating, details, and link from currently visible product cards.

Use this after jev_browse reaches a results or product page. This is best-effort read-only DOM extraction; it does not scroll, click, or infer fields that are not visible, so verify important price or stock data.

Inputs: session_id (required).

jev_statusA

Inspect a live Jev browser session without taking another browser action.

Use it after jev_browse to reason from the current URL, visible text, supported controls, and recent actions. It does not load a page, click a control, scroll, or generate model requests.

Inputs: session_id (required).

jev_stopA

Close one Jev-owned Chrome target and remove its session.

Call this when product research is complete or after an unrecoverable block. The session_id becomes invalid immediately; this never affects tabs outside the Jev-owned browser target.

Inputs: session_id (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: browse starts/advances sessions, status inspects without acting, extract parses visible product cards, and stop closes the session. There is no functional overlap or ambiguity between them.

    Naming Consistency4/5

    All tools share the 'jev_' prefix and are short, readable command-style names. 'jev_status' is a noun rather than a verb like the others, but this is a minor deviation that does not harm predictability.

    Tool Count5/5

    Four tools are well-scoped for a read-only browser automation server focused on product research. Each tool serves a distinct stage in the session lifecycle with no redundancy.

    Completeness5/5

    The tool set covers the full workflow: start/advance browsing, inspect session state, extract product data, and close the session. There are no obvious dead ends or missing lifecycle operations for the stated purpose.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      Provides browser automation and web scraping as MCP tools, enabling autonomous URL ingestion, crawling, extraction, and anti-bot handling with interactive browser control.
      62
      6
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Browser-based research MCP server that drives a real Chromium browser via patched Playwright to access JavaScript-rendered content, dynamic tables, and login-walled dashboards. It provides tools for visiting URLs to extract DOM text and screenshots, and for performing structured data extraction using Anthropic Claude Sonnet.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local browser control via Chrome/Edge extension, enabling agents to open isolated tabs, observe pages, take screenshots, and interact with accessible controls using an existing browser profile. It is agent-agnostic, local-only, and supports safe session scoping with origin grants and sensitive-data blocking.
      MIT