jev-mcp
This server provides a read-only, session-aware MCP interface for product research on public websites using Jev's browser agent.
jev_browse: start a browser session for a public URL and goal, up to 30 steps, then return session ID, evidence, and actions.jev_status: inspect a live session's URL, visible text, supported controls, and recent actions without acting.jev_extract_products: extract visible product cards (name, price, rating, details, URL) from a results or product page.jev_stop: close a Jev-owned Chrome target and invalidate the session; does not affect ordinary tabs.jev_decide: act as a relay-only decision maker using host-supplied page state; never opens a browser or takes page actions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jev-mcp Search Amazon for running shoes under $80 and extract product details."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Start a public-site search, filtering, or product-detail task | Log in, checkout, pay, upload, or submit an order |
| Read a session's URL, visible text, supported controls, and latest actions | Take another browser action |
| Read visible product card fields: name, price, rating, details, URL | Scroll, click, or guarantee site-specific parsing |
| Close the Jev-owned Chrome target | Affect ordinary user Chrome tabs |
| 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+
A Chrome/Chromium installation supported by
browser-harnessAn
OPENROUTER_API_KEYfor Jev Decisions (recommended), or a directTYPESAFE_API_KEYTEXT_MODEL_API_KEYfor 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 --doctorbrowser-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-mcpThe 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
Call
jev_browsewith a public URL and a narrow goal, for example: “Search wireless headphones, set the price filter below $100, and stop when results are visible.”Keep the returned
session_id.Call
jev_statuswhen you need to decide whether the page is ready or why it blocked.Call
jev_extract_productson a visible result/detail page.Call
jev_stopwhen 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-mcpThe 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 toolsjev_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
Scored across 4 tools
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.
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.
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.
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
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
A paid remote MCP for AI agent browser MCP session, built to return verdicts, receipts, usage logs,
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Federated commerce search across independent WooCommerce merchants. Keyless, read-only MCP server.
Related MCP Servers
- AlicenseCqualityDmaintenanceProvides browser automation and web scraping as MCP tools, enabling autonomous URL ingestion, crawling, extraction, and anti-bot handling with interactive browser control.626MIT
- AlicenseAqualityBmaintenanceBrowser-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.3Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP 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
- FlicenseNot gradedqualityDmaintenanceMCP server for automating personal Amazon.in and Flipkart accounts via browser sessions, enabling product search, cart management, and guarded checkout.-