jev-mcp

jev-mcp is an MCP server that hands the browser agent jev-ultrafast to Claude Code and Claude Desktop. You give it a start URL and your goals in plain sentences, and it operates the page on its own in your real, already logged-in Chrome. A TypeSafe decision model (Jev) picks every step, and a separate text model writes the values that get typed into fields.

Requirements

• Python 3.12 or newer

• uv

• Google Chrome, driven through browser-harness

• A TypeSafe API key (TYPESAFE_API_KEY). Without it no run starts at all, because nothing can choose an action, not even a click or a scroll.

• A text model key. Without it the agent can still click, scroll, navigate and pick from dropdowns, but it cannot type, so forms and search fields stay empty.

• git and access to GitHub during install. jev-ultrafast is not published on PyPI, so it is installed straight from its repository, pinned to the exact commit this server was tested against.

Related MCP server: Browser Tools for Claude Code

Setup

git clone https://github.com/SAITS-Swiss-AI-Tech-Services/jev-mcp.git
cd jev-mcp
uv sync

Put the keys into ~/.config/jev-mcp/env. The format is NAME=VALUE, one entry per line. Empty lines and lines starting with # are skipped, a leading export is stripped, quotes around a value are removed, and a trailing comment is cut off. The file is read only when it is a regular file of at most 256 KiB.

TYPESAFE_API_KEY=...
MOONSHOT_API_KEY=...

Claude Desktop inherits no shell, which is exactly why this file exists. Claude Code does inherit the shell, so keys already exported there are found as well.

The server looks for the text model key by provider first and by source second. It tries TEXT_MODEL_API_KEY, then Kimi (MOONSHOT_API_KEY, KIMI_API_KEY), then DEEPSEEK_API_KEY, then OPENROUTER_API_KEY, and inside each of those steps the process environment before the file. The first hit wins and decides the provider, including base URL and model name. For TYPESAFE_API_KEY there is only one variable, and there the environment simply beats the file.

Register the server in Claude Code. Use the absolute path to uv:

claude mcp add jev-browser --scope user -- /absolute/path/to/uv run --directory /absolute/path/to/jev-mcp jev-mcp

Register it in Claude Desktop by adding the same command to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Both entries need absolute paths, because Claude Desktop does not inherit your shell environment and therefore does not find uv on the PATH. command -v uv prints the path. Restart both clients afterwards, they only load new servers on start.

Finally, allow Chrome to be driven. Once: open chrome://inspect/#remote-debugging and tick "Allow remote debugging for this browser instance". After that, Chrome asks once per browser session whether a connection may be made. See Troubleshooting for the reliable way to answer it.

The three tools

browser_task(url, goals, max_actions, time_budget_s, allow_domains, dry_run)

Operates a site autonomously: it opens url and pursues goals, deciding every click, selection and keystroke without asking.

The result reports the status, the final URL, the page title, every executed step, the duration, the actions and model calls used, the reason it stopped and, for a dry run, the step it would have taken next.

browser_status()

Read-only diagnosis, and free: it opens no browser, loads no page and calls no model. It says which keys were found and where they came from, which text model would type, whether the browser-harness daemon is running and whether a Chrome is connected to it, and which operations are blocked as a result. Call it before the first run of a session and whenever one of the other two tools fails.

browser_read(url, time_budget_s, allow_domains, text_limit)

Opens one page and returns its visible text plus the table of operable elements, without clicking, typing or selecting anything.

The answer says how long the text was before truncation, and it lists at most 120 elements. A redirect onto another registrable domain is reported, and nothing from that page is returned.

Limits, stated up front

The agent underneath is an MVP, and these gaps are real:

• It cannot see into iframes, and it cannot see into shadow DOM.

• It cannot upload files.

• It cannot follow pop-up tabs.

• It only observes the visible viewport. It scrolls, but it never reads what is not rendered.

• Only one run can be in flight at a time. A second call is refused immediately with not_started instead of being queued, because a run writes process-wide values into os.environ and two runs would overwrite each other.

• A call blocks until the run ends.

• The agent works inside your real, logged-in Chrome profile. Whatever it clicks happens in your sessions, for real. Each run opens its own background window and closes it afterwards. It does not use a background tab, because Chrome 153 answers no command sent to a background tab created over the DevTools protocol, while a background window works and leaves your own window alone.

• Result messages are in German. The tool descriptions, which the model reads, are in English.

• Do not put credentials into goals. The goal text comes back verbatim in the result, and so does every value the agent typed into a field. Nothing of that is masked, on purpose: the typed text is the most important record of what the agent actually did. Password, file and hidden fields are excluded from observation, so nothing is typed there, but a one-time code or a customer number in an ordinary text field is not covered by that and will appear in the result.

• Logging in, paying, ordering and submitting forms on banking or payment sites are out of scope for this project.

The safeguard: domain fidelity instead of a blocklist

There is no blocklist. That was a deliberate decision: the agent only ever runs on request, so there are no forbidden domains. Instead a run remembers the registrable domain of its start URL. If a click or a redirect would take it to a different registrable domain, it stops and reports where it wanted to go, rather than acting there. Subdomains of the same registrable domain count as the same domain.

The check runs at two moments. Before a navigation it uses the address the next step would open, and that is the check that actually protects you, because in a logged-in profile the loaded page is already the damage: it has seen cookies, run scripts and sent requests. After every load it uses the address the browser actually ended up on, which catches redirects, window.location from a script and clicks the agent did not recognise as navigation. A block at that second moment means the damage has already happened, and the run aborts instead of continuing.

When the module cannot read its own input reliably, it blocks. An unreadable start URL, a host with characters outside the permitted set, an invalid port, a numeric address that does not parse: all of those end in a block, never in a pass.

What it explicitly does not do:

• It does not judge content. What an allowed page whispers to the agent is invisible to it, and page content can steer the decision model.

• It knows no confirmation prompt and no step limit. Those live in the runner.

• Before a click it can only read a target address from a real link (a[href]). A <button>, a form submission or a click that only a script turns into navigation contributes nothing, and there the check first bites after the load.

Known weakness with hosting suffixes: the module does not use the Public Suffix List, which would be a dependency. It applies the rule "the last two labels", extended by a built-in set of multi-part suffixes that covers the common country suffixes and the common hosting suffixes such as github.io and vercel.app. A multi-part suffix that is missing from that set, blogspot.de for example, is read too loosely, and two unrelated sites under the same provider then count as the same domain. The opposite error, a three-label host whose middle label happens to look like a suffix, makes the check too strict, and the agent stops although it would have been allowed.

The check can be relaxed in four places: allow_domains per call, allow_domains globally in ~/.config/jev-mcp/policy.toml, the switch enforce_domain_lock = false in the same file, and allow_unbound for runs that are meant to start without a domain binding.

Choosing the text model

Measured on 2026-09-20 through a real jev_ultrafast.model.field_text() call, filling the field "Where from?" in a flight search. All four runs answered correctly ("Zurich"):

K3 costs five times as much latency, and it costs it per typed field. K3 is the default anyway, by explicit decision. Switching is one line in ~/.config/jev-mcp/env, and the provider stays the same:

TEXT_MODEL=kimi-k2.7-code-highspeed

Troubleshooting

Call browser_status first. It names the missing key, the missing daemon or the missing Chrome connection and says what is blocked because of it, which is faster than guessing.

If it reports that the browser-harness daemon is not running, or that it runs but no Chrome is connected to it, browser-harness --doctor diagnoses install, daemon and browser state.

Chrome asks for approval once per browser session. The reliable way to answer it: bring a normal Chrome window to the front, not in full screen, then run the command below and click Allow in the dialog. It waits without a time limit.

cd /absolute/path/to/jev-mcp && echo 'print(page_info())' | uv run browser-harness

browser-harness mac-approve can click the dialog for you on macOS, but only when Chrome's interface is in English: it matches the English dialog text. It also needs the Accessibility permission for your terminal.

If a run is refused with not_started and a note about concurrency, another run is still in flight. Wait for it and start again.

Development

uv run pytest
uv run ruff check .

461 tests pass as of 2026-09-21. The suite runs without a browser and without network access, against test doubles and against contract tests that pin every assumption about jev-ultrafast to its installed source. An end-to-end run against real Chrome 153 through the server as a separate stdio process passed on 2026-09-21.

Built on

jev-mcp is a thin, guarded layer. The actual work is done by these projects:

The text that gets typed into fields comes from an OpenAI-compatible model of your choice. The server knows Moonshot Kimi, DeepSeek and OpenRouter by name and works with any other endpoint through TEXT_MODEL_API_KEY and TEXT_MODEL_BASE_URL.

Related: typesafe-mcp (MIT) exposes the same Jev model as a general judgment tool, typed answers with probabilities, for any MCP client.

Security

This server drives a real, logged-in browser, and its only safeguard is the domain check described above. If you find a way around it, please report it privately to hello@saits.ai instead of opening a public issue.

License

MIT, see LICENSE. Copyright (c) 2026 R. Schröder GmbH (SAITS - Swiss AI Tech Services).