Genkan

Your AI waits at the genkan.

English | Simplified Chinese | Traditional Chinese

A program you installed cannot use your browser without you noticing. Under that bar, genkan lets any MCP client (Claude Code, Claude Desktop, Codex, or anything that speaks the Model Context Protocol) drive your real Chromium browser: your tabs, your logged-in sessions, your cookies, through a browser extension and a native-messaging host. No second browser, no CDP debug port, no --remote-debugging flag.

Because it operates the browser you are already signed into, an agent can read a page behind your auth, click through an app you are logged into, or pull a token your framework stashed in localStorage. That power is also the risk, so read Security first before you install. Where the bar stops is stated on the security page.

Features

• Your real browser, not a headless one: 26 tools over tabs, pages, cookies, and storage, each with a stated risk level and gate (below).

• Guardrails on by default: per-site approval, confirmation of the dangerous actions in a window no page can reach, presence by WebAuthn, a kill switch, an audit trail (Security first).

• An authenticated, attested bridge between the MCP server and the browser's host, with no listening port (How it works).

• Several clients at once, each attested and individually revocable.

• One binary, three roles: the MCP server, the native-messaging host, and the CLI that installs, pairs, kills, and audits.

Related MCP server: universal-browser-bridge

Security first

genkan drives a real, authenticated browser. It can read page content, cookies (including httpOnly), and web storage, and can run JavaScript in your pages. The guardrails:

• Approve every site. Page-level tools run only on origins you approved, and a new origin prompts you; tab titles and URLs alone need no approval (the matrix, the bar).

• Confirm high-risk actions. Submit and link clicks, key presses, selects, tab close, file uploads, and every page_eval confirm on an extension-owned window the page cannot see or click; page_eval and page_upload reconfirm on every call (what you confirm). What a same-user program can still do around that window is in the trust boundaries ledger.

• Prove presence with WebAuthn. Releasing the kill switch needs a tap from an authenticator enrolled under that browser, and enrolling another browser needs a tap from any authenticator already enrolled on the machine; the host verifies both. The confirmation window stands in only where no enrolled authenticator could answer (what counts as presence).

• Gates are on by default. Each is a documented setting, and relaxing one is an explicit, informed choice (SECURITY.md).

• Cookies and web storage are read-only. cookie_get and storage_get return masked values and never write (the matrix); what the mask catches and misses is SECURITY.md's.

• Authenticated, attested bridge. No listening port on any OS: a private Unix-domain socket on macOS and Linux, a named pipe only your user can open on Windows. Every connection passes a same-user check, mutual executable attestation, and an HMAC challenge over a per-run secret; the per-OS mechanism is SECURITY.md's platform table.

• Trusted-client allowlist, once you create it. genkan pair-client creates it; from then on only MCP clients whose attested code identity you approved are served, and any surface can revoke one at any time (cli.md).

• A global kill switch. One action from the CLI or the extension halts everything until you release it with proof of presence (a tap, the confirmation window where that browser enrolled no authenticator, or the typed phrase on a terminal; cli.md). Security decisions land in an on-disk audit trail (cli.md owns the event list and its two exceptions).

Full details: SECURITY.md, security page, trust boundaries, per-tool risk matrix.

Requirements

Pre-1.0 (Cargo.toml): the protocol layers are covered by end-to-end, adversarial, and chaos tests, and the wire parsers are fuzzed (CHANGELOG.md).

Quick start

The CLI needs nothing beyond the binary itself, on desktops, headless machines, and CI alike. The steps in full, with the install channels and what each does for you, are in the quickstart; the short form:

1. Install from the latest release: the .pkg, the .msi, the .deb, Homebrew (once the tap exists), or the archive. To verify a download first, the commands are in SECURITY.md.

2. Register the binary with your browsers, unless the installer did: .pkg, .msi, and Homebrew do, and the .deb does for browsers installed at the time (quickstart step 3). The command is idempotent: fresh install, repair, and re-register after moving the binary:

   genkan doctor --fix          # every detected browser
   genkan doctor --fix --browser chrome,brave

   From the archive, run the extracted binary with a ./ prefix from a stable path: it is registered in place, and genkan uninstall reverses exactly what was registered.

3. Load the extension: the archive's extension/dist directory via chrome://extensions, Developer mode, "Load unpacked". Restart the browser. The extension needs Chrome 134 or later; an older browser refuses to load it.

4. Pair, then enroll (recommended): genkan pair prints the host key's fingerprint; approve it on the extension's options page (docs/cli.md). Enrolling your browser's authenticator from the same page is recommended, not required; the quickstart's hardening section says what it adds.

5. Connect your MCP client to the binary's absolute path. Run with no arguments, the binary speaks MCP over stdio.

   claude mcp add genkan -- /absolute/path/to/genkan

   Claude Desktop and other mcpServers JSON clients take "command": "/ABSOLUTE/PATH/TO/genkan" with "args": []; Codex takes the same two keys under [mcp_servers.genkan] in ~/.codex/config.toml.

Building from source instead: cargo build --release, then run the same doctor --fix from target/release/genkan (docs/development.md). On WSL, install where the browser runs (running under WSL).

What you can do: 26 tools

Grouped from the single source of truth, the Rust tool catalogue (src/packages/core/src/tools/catalogue.rs); the blast radius and the gate of every tool are in the tool risk matrix.

Several browsers can be connected at once. A browser that alone launches its manifest connects under its own label, while browsers sharing one manifest share the broker's default slot (cli.md says which share); every other tool takes an optional browser argument, and an unaddressed call with several connected fails rather than guessing (the matrix).

Cookies and web storage are read-only by design: there is no cookie_set or storage_set, since a forged httpOnly cookie is a session-fixation risk (the matrix).

How it works

One Rust binary, two modes, joined by an authenticated local socket; the CLI manages the state.

MCP client A --stdio--> genkan (broker: first MCP server instance)
MCP client B --stdio--> genkan ----attach----^   |
(each client attested against the trusted-client         | bridge socket
 allowlist before it is served)                          | (Unix-domain socket,
                                                          | or a user-only named pipe
                                                          | on Windows; attestation + HMAC)
                                                          v
                             genkan --native-host   <-- spawned by
                                       |                         each browser
                                       | chrome.runtime.connectNative
                                       v
                             Genkan extension (MV3) --> your page

• MCP server (default mode): launched by your MCP client over stdio; JSON-RPC 2.0, MCP protocol 2026-07-28, stateless, with temporary legacy compatibility for older harnesses (architecture.md 3.2). The first instance owns the socket and becomes the broker; later instances attach as relays (5.3).

• --native-host: launched by the browser via the host manifest, one per browser, under the label cli.md gives that manifest; a thin bridge from Chrome's native-messaging frames to NDJSON on the socket.

• CLI: the management surface over the same core (registration, pairing, revocation, kill switch, audit). It is not a trust root; capability-granting acts end in a user-presence gate.

The browser spawns the native host and the MCP client spawns the server, so they are not parent and child and need an IPC; the host stays thin so that MV3 service-worker recycling (about every 5 minutes) and host restarts lose no session state. The deep dive is docs/architecture.md.

Configuration

Environment variables read at launch:

The durable audit trail (genkan audit) records independently of these (docs/cli.md).

Documentation

The docs are served at https://vivswan.github.io/genkan/docs/, in English, Simplified Chinese, and Traditional Chinese; the same pages live under docs/.

Contributing and governance

CONTRIBUTING.md is the workflow, GOVERNANCE.md how changes get made, SECURITY.md the reporting channel and the review bar, and tests/README.md the suites and the browser-safety rule.

License

Individual and Small Organization License 1.1.0. Incorporates code from browser-bridge under Apache-2.0; see LICENSE-APACHE and NOTICE.