Jev + GemLogin Browser Bridge

Bounded browser-control MCP server for using Jev to make typed decisions from the current GemLogin browser state. It starts a GemLogin profile, attaches Playwright over CDP, exposes the current page as bounded text and accessible elements, and sends that state to Jev for structured decisions.

Jev does not execute arbitrary code or click by itself. The available browser actions are intentionally limited to starting a profile, inspecting, navigating to HTTP(S), clicking by accessible role/name, and filling an accessible textbox or combobox.

Requirements

Install or prepare these before starting the MCP server:

1. Python 3.11 or newer and pip.
2. GemLogin Desktop / Local API, running on the same machine. The bridge expects the default API at http://localhost:1010.
3. At least one usable GemLogin profile ID.
4. A valid Jev API key.
5. An MCP-compatible host such as Codex, Claude Desktop, or another MCP client.
6. Network access to the configured Jev endpoint.

Playwright is installed as a Python dependency. No separate browser download is required because the bridge connects to the browser launched by GemLogin over CDP. If your environment uses Playwright independently, you may additionally run python -m playwright install chromium.

Install

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Dependencies used in the latest workflow

The latest GemLogin video-search workflow was verified on 2026-09-22 with the following packages installed in the local .venv:

Package	Version used	Role
httpx	0.28.1	Call the GemLogin Local API and Jev API
mcp	1.30.0	Expose the MCP server and tools
playwright	1.63.0	Attach to the GemLogin browser over CDP
pytest	9.1.1	Run the test suite
pytest-asyncio	1.4.0	Test async browser/API code
respx	0.23.1	Mock HTTP requests in tests

The installation also brings transitive dependencies required by those packages, including anyio, httpcore, pydantic, uvicorn, jsonschema, and related support libraries. They are resolved automatically by pip from pyproject.toml.

No new production dependency was added specifically for the video search: the workflow used the existing MCP tools jev_gemlogin_start, jev_gemlogin_navigate, and jev_gemlogin_inspect. No separate Playwright browser binary was installed because Playwright attaches to the browser already launched by GemLogin through CDP.

Configure the Jev API key

The key is read from the JEV_API_KEY environment variable. Put it in the MCP client's environment, not in the source code and not in Git.

Option A: temporary shell configuration

export JEV_API_KEY="your-real-jev-api-key"
export GEMLOGIN_BASE="http://localhost:1010"
export JEV_ENDPOINT="https://jev-ai.pro/api/v1/systemone"
export JEV_MODEL="jev-latest"

Option B: local .env file

cp .env.example .env

Edit .env and replace replace-with-your-jev-api-key. The .gitignore already excludes .env. This project does not load .env automatically; use your MCP host's environment-file support or export the variables before starting the server.

Never commit the real key. The jev_gemlogin_status tool only reports whether a key is configured; it never returns the key.

Register with Codex

From the project directory:

codex mcp add jev-gemlogin-browser \
  --env JEV_API_KEY="your-real-jev-api-key" \
  --env GEMLOGIN_BASE="http://localhost:1010" \
  --env JEV_ENDPOINT="https://jev-ai.pro/api/v1/systemone" \
  -- \
  "$PWD/.venv/bin/python" -m jev_gemlogin_bridge.server

If the environment is already exported, the shorter form works:

codex mcp add jev-gemlogin-browser \
  -- "$PWD/.venv/bin/python" -m jev_gemlogin_bridge.server

For other MCP clients, configure the equivalent stdio server command:

Command: /absolute/path/to/jev-gemlogin-bridge/.venv/bin/python
Arguments: -m jev_gemlogin_bridge.server
Environment: JEV_API_KEY=your-real-jev-api-key

Typical MCP flow

1. Start GemLogin Desktop and confirm its Local API is available.
2. Call jev_gemlogin_status to verify configuration.
3. Call jev_gemlogin_start(profile_id).
4. Call jev_gemlogin_navigate(url) or inspect the existing page.
5. Call jev_gemlogin_inspect() to read bounded page state and accessible elements.
6. Call jev_decide(instruction, questions) with a bounded choice, score, or noul schema.
7. Inspect Jev's decision before invoking the selected safe action.
8. Call jev_gemlogin_click or jev_gemlogin_type and inspect again after a page transition.

To run a stored workflow directly, call jev_workflow_run with its workflow ID, profile IDs, and parameter values. Use jev_workflow_status to poll the run and jev_workflow_stop to stop it. The run tool passes through only the workflow parameters plus explicit execution options; it does not read or expose cookies, passwords, or API keys.

The server does not bypass login, extract cookies, expose passwords, or return the Jev API key.

Tools exposed

Tool	Purpose
jev_gemlogin_status	Show non-secret configuration and readiness
jev_gemlogin_start	Start a GemLogin profile and attach over CDP
jev_gemlogin_inspect	Read URL, title, bounded visible text, and interactive elements
jev_gemlogin_navigate	Navigate to an HTTP(S) URL
jev_gemlogin_click	Click an accessible element by role and name
jev_gemlogin_type	Fill an accessible textbox or combobox
jev_decide	Ask Jev to choose among caller-defined typed options
jev_workflow_run	Start a stored workflow on selected profiles
jev_workflow_status	Check whether a workflow is running
jev_workflow_stop	Stop a workflow on selected profiles

Test

python -m pytest tests -q

Security notes

• Keep JEV_API_KEY in the MCP host environment or an untracked .env file.
• Do not commit cookies, browser profiles, passwords, or session exports.
• Use only profiles and websites you are authorized to access.
• Navigation is restricted to HTTP(S), and page text/elements are bounded before they are sent to Jev.