Jev Browser MCP

A local MCP server that lets a coding agent carry out bounded browser tasks. By default, it starts a dedicated, visible, maximized Chrome window on a loopback CDP port and reuses that browser when the MCP server restarts. Jev selects each next action from the live page's visible controls and links. The server performs only those listed actions and returns the resulting page evidence to the MCP client.

What it exposes

• browser_discover finds local Chromium and Electron CDP endpoints on ports 9222 and 9223, the configured default port, or a caller-supplied list of ports.

• browser_connect switches the running Jev MCP session to a discovered local browser, then returns its version and tabs. Omitting browserUrl switches back to the configured default browser.

• browser_tabs lists open pages.

• browser_inspect returns a text snapshot and visible interactive controls for one page.

• browser_task follows a natural-language goal through a bounded sequence of Jev-selected page actions. It can also choose relevant Chrome DevTools operations such as accessibility snapshots, screenshots, console and network inspection, CSS inspection, emulation, Lighthouse audits, performance traces, and page management when the needed arguments are grounded in the request and current page.

• browser_devtools_catalog reports every operation and input schema exposed by the installed Chrome DevTools MCP backend.

• browser_devtools forwards a named operation and its arguments to that backend. This provides the full operation set from the installed chrome-devtools-mcp version, including operations that Jev cannot safely parameterize from a natural-language goal alone.

The server delegates the low-level CDP implementation to Chrome DevTools MCP. browser_task only offers Jev actions with concrete arguments drawn from the user request and live page evidence; it does not let Jev invent selectors, file paths, or page JavaScript. Password fields are omitted from Jev's browser snapshot. Jev is the fast decision path for ordinary actions. When Jev confidence is below the threshold, browser_task returns needs_llm_review and available action keys; the calling LLM can choose one by resuming with taskId and fallbackActionKey, revise the goal, or ask the user. When Jev has no grounded candidate for a DevTools operation, it routes the request to the calling LLM to select an operation from browser_devtools_catalog. Sensitive actions are also returned to the calling LLM for review and remain paused until user confirmation. A task stops when it needs clarification or reaches its step limit.

Jev task actions support HTTP(S) pages and about:blank. Browser-internal pages and local files are excluded. The low-level DevTools passthrough follows the capabilities and restrictions of the installed Chrome DevTools MCP backend.

Jev chooses actions; it does not write a natural-language answer. The MCP client receives the final snapshot and can summarize it for the user.

Related MCP server: chrome-devtools-mcp

How and where Jev is used

Jev is the decision layer inside browser_task. The MCP server first reads the current page and builds a snapshot of its text, URL, title, visible controls, and recent browser actions. It passes that snapshot with the user's goal to the TypeSafe Jev API. Jev returns one choice from the actions the server has already prepared, such as clicking a visible control, entering user-provided text, choosing a visible option, navigating to a requested URL, scrolling, or finishing the task. The server checks the returned choice against that prepared action list, then carries it out through the browser connection.

The TypeSafe integration lives in src/decision.ts; the browser_task loop and action execution live in src/index.ts. Jev is also used when a task needs to choose among exact text spans taken from the user's request or visible select options. It does not generate arbitrary form text. A single available text or select option can be handled locally without an API call.

Jev is not called by browser_discover, browser_connect, browser_tabs, or browser_inspect. Those tools read or connect to the local browser directly. browser_devtools_catalog and browser_devtools also bypass Jev: the caller chooses the exact DevTools operation and arguments. During browser_task, Jev may choose a DevTools operation only from candidates the server has grounded in the request, current page, and installed DevTools catalog.

The API key is read from TYPESAFE_API_KEY in the MCP host environment, and TYPESAFE_DEFAULT_MODEL can optionally select a default Jev model. browser_task sends the goal and page evidence to TypeSafe so Jev can make its choice; URL query strings and fragments are removed first. If Jev's confidence is below 0.65, the server pauses and returns the available actions to the calling LLM for review. Actions that require user confirmation remain paused until the caller confirms them.

Requirements

• Node.js 22 or newer

• A TypeSafe API key

• Google Chrome, or Chromium/Electron with a local remote-debugging endpoint compatible with Chrome DevTools Protocol

Install and build:

npm install
npm run build

By default, the MCP server launches Google Chrome automatically with a dedicated profile at ~/.cache/jev-browser-mcp/chrome-profile, maximizes the window, and listens on http://127.0.0.1:9223. Jev and the DevTools backend attach without imposing a fixed page viewport, so the page uses the available browser window size. Keep that Chrome window open between MCP sessions; Jev reconnects to it on the next start. A separate Chrome DevTools MCP can use the same browser by connecting to that URL.

The MCP declaration only needs to point at Jev Browser once. Browser selection happens at runtime: call browser_discover, then browser_connect with the returned browserUrl. The active browser is shared by browser_tabs, browser_inspect, browser_task, and the DevTools tools. Switching browsers invalidates old tab IDs and pending task confirmations. Runtime-selected endpoints are attach-only; if one is not available, Jev reports the connection error and returns to the previous selection. Call browser_connect without a URL to restore the configured default.

For example, to discover and attach to an Electron app that exposes CDP on port 9222:

{}

Call browser_discover with the empty object above, then connect using the endpoint it returns:

{
  "browserUrl": "http://127.0.0.1:9222"
}

That object is the input to browser_connect. If your app uses a different port, pass it to browser_discover, for example { "ports": [9333] }.

To attach to an existing Chromium or Electron instance instead, start it with a dedicated profile and loopback-only CDP endpoint. For example:

chromium --start-maximized --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir=/path/to/jev-browser-profile

Replace /path/to/jev-browser-profile with a directory you control. --start-maximized opens a regular maximized window; Jev attaches to that window and does not change the operating-system window size itself. Chrome 136 and newer require a non-default user data directory for remote debugging; see Chrome's remote debugging security change.

For Electron, enable the Chromium remote-debugging port in the main process before the app becomes ready:

const { app } = require('electron');
app.commandLine.appendSwitch('remote-debugging-port', '9222');

Electron exposes CDP when this switch is enabled. Discover its port and connect at runtime; you do not need to edit the MCP declaration or restart Jev for each browser. Individual DevTools operations still depend on the Chromium/CDP version bundled with that Electron release. See Electron's supported command-line switches.

Set these environment variables in the MCP host configuration:

• TYPESAFE_API_KEY (required for browser_task)

• TYPESAFE_DEFAULT_MODEL (optional; pin a concrete Jev model)

• BROWSER_CDP_URL (optional; defaults to http://127.0.0.1:9223; if no browser answers there, Jev launches Chrome on that port)

• BROWSER_USER_DATA_DIR (optional; overrides the managed Chrome profile directory)

• BROWSER_EXECUTABLE_PATH (optional; use a specific Chrome/Chromium executable instead of installed Google Chrome)

• BROWSER_HEADLESS (optional; set to true to launch without a visible window)

When the browser has no pages open, the server creates a blank tab. For an explicit web search request such as “search the web for TypeSafe Jev”, it offers the Google home page as a navigation candidate; Jev still chooses whether to use it.

Example stdio MCP configuration:

{
  "mcpServers": {
    "jev-browser": {
      "command": "node",
      "args": ["/absolute/path/to/jev_browser_mcp/dist/index.js"],
      "env": {
        "TYPESAFE_API_KEY": "<your-key>",
        "BROWSER_CDP_URL": "http://127.0.0.1:9223"
      }
    }
  }
}

Calling Chrome DevTools operations

Use browser_task for natural-language goals so Jev can choose the actions. Use browser_devtools_catalog and browser_devtools when the calling LLM intentionally selects an exact low-level operation and arguments. The catalog reports every operation and schema from the installed backend. For page-scoped calls, tabId selects the page; when omitted, Jev Browser uses the only open page. The bridge resolves Chrome DevTools MCP's numeric page ID and selects that page automatically where needed.

Example calls:

{
  "toolName": "take_screenshot",
  "arguments": {},
  "tabId": "tab-1"
}

{
  "toolName": "list_network_requests",
  "arguments": {},
  "tabId": "tab-1"
}

The result preserves the upstream MCP content, including image blocks. For sensitive operations, the first call returns a confirmationId; after the user confirms, repeat the same operation and arguments with that ID and confirmSensitiveActions: true.

Data and safety

The browser_task request sends the task, current page text, page title, URL origin/path, and visible control labels to TypeSafe so Jev can choose an action. URL query strings and fragments are removed before URLs in the task and page text are sent. Page content is untrusted evidence; it cannot add actions to Jev's fixed candidate set. DevTools result content is returned to the MCP caller and is not sent to Jev. Do not use this on pages whose contents you do not want sent to TypeSafe. Password fields are omitted; do not include passwords or other credentials in the task text.

CDP grants powerful control over the attached browser. Keep the endpoint on loopback, use a dedicated browser profile, and attach only to a browser you intend to automate. browser_devtools can expose browser debugging data and perform powerful page actions; use it only with a browser you intend to control. The server disconnects its CDP clients when it exits; it does not close the managed Chrome window. If Chrome exits while the MCP server is still running, the next browser call starts it again automatically.

For external or consequential actions such as sending, buying, deleting, publishing, or saving a change, first get the user's confirmation. Jev returns needs_llm_review with fallbackReason: "sensitive_action"; the calling LLM reviews the proposed action and asks for confirmation. Resume with taskId and confirmSensitiveActions: true only after confirmation. The server only applies that confirmation to the same pending action. For a low-confidence Jev choice, resume with taskId and a returned fallbackActionKey to let the calling LLM make that one action decision. For clarification, resume with the same taskId and the updated goal. Sessions are held in memory and expire when the MCP server restarts.

Development

npm run dev

The server communicates over stdio. Logs go to stderr so MCP JSON-RPC traffic stays on stdout.

License

This project is licensed under the MIT License. See LICENSE for details.