nekoro-browser 0.2.0

Lightweight browser automation CLI + MCP server. Drives your everyday Chrome through an extension — keeps your login state, no debug port, no banners.
_中文

Quick Start · Examples · MCP · API · Architecture · Site Knowledge · Limitations · Reference

Quick Start

1 — Install (Python 3.12+, zero third-party dependencies)

uv tool install nekoro-browser

Installs both commands (nekoro-browser, nekoro-browser-mcp) into their own environment, so nothing lands in your system Python. No uv? pipx install nekoro-browser works the same way.

_{From source: git clone https://github.com/zeshuochen/nekoro-browser && cd nekoro-browser && uv pip install -e .}

Upgrading? uv tool upgrade nekoro-browser updates the Python side only. The extension Chrome already loaded keeps running the old background.js, so anything that touches the extension silently stays on the old behaviour. Reload it after every upgrade: nekoro-browser --reload-ext (or Reload on the card in chrome://extensions). Run nekoro-browser --doctor afterwards to confirm the service worker answers.

2 — Load the extension

nekoro-browser setup

setup copies the extension directory to your clipboard and then waits — up to three minutes — until the extension actually connects, so you find out it worked instead of guessing. Meanwhile you do the part Chrome reserves for humans: open chrome://extensions/, turn on Developer mode, click Load unpacked, paste the directory.

3 — Start the daemon — give it its own terminal and leave it open; it runs in the foreground and closing that window stops it

nekoro-browser

4 — Drive the browser from anywhere else

echo "page_info()" | nekoro-browser
# → {"ok": true, "result": {"title": "...", "url": "..."}}

That's it. If step 4 says the daemon isn't running, or a command times out, run nekoro-browser --doctor — it checks the daemon, the extension and the service worker separately and tells you which one is down.

Why Not --remote-debugging-port?

Since Chrome 136, --remote-debugging-port / --remote-debugging-pipe refuse the default profile — you must point Chrome at a non-default --user-data-dir, i.e. a clean instance with none of your logins. An extension's chrome.debugger is not subject to that restriction, which is why nekoro goes through an extension.

Examples

Send a multi-step flow in one shot with a heredoc. Every helper is a top-level await:

nekoro-browser <<'PY'
await new_tab("https://example.com")
print((await page_info())["title"])            # Example Domain
print((await get_markdown(max_chars=200))["result"])
print((await state(max_items=3))["result"])    # indexed interactive elements, model-ready
await close_tab()
PY

state() numbers the elements and click_index(n) clicks by number — the model never has to guess a CSS selector:

nekoro-browser <<'PY'
await navigate("https://github.com/search?q=browser+automation&type=repositories")
await wait_for_load()
print((await state(max_items=40))["result"])
await click_index(12)
PY

All helpers are documented in SKILL.md.

MCP (any MCP client)

Every function in helpers.py is reflected into an MCP tool (46 today) — no glue code.

Prerequisite: the daemon must be running (nekoro-browser, its own terminal). The MCP server is a thin forwarder — it talks to that daemon over the same authenticated path as echo ... | nekoro-browser, and the daemon is what owns the Chrome connection.

The command to register is always nekoro-browser-mcp. Only the config shape differs:

Claude Code

claude mcp add nekoro-browser -- nekoro-browser-mcp

Claude Desktop (Settings → Developer → Edit Config) · Cursor (~/.cursor/mcp.json, or .cursor/mcp.json for one project) · Cline (MCP Servers → Configure MCP Servers)

{ "mcpServers": { "nekoro-browser": { "command": "nekoro-browser-mcp" } } }

_{Claude Desktop config file: macOS ~/Library/Application Support/Claude/claude_desktop_config.json · Windows %APPDATA%\Claude\claude_desktop_config.json}

opencode (opencode.json) — note command is an array, and the key is mcp

{ "mcp": { "nekoro-browser": { "type": "local", "command": ["nekoro-browser-mcp"], "enabled": true } } }

Codex (~/.codex/config.toml, or codex mcp add nekoro-browser -- nekoro-browser-mcp)

[mcp_servers.nekoro-browser]
command = "nekoro-browser-mcp"

VS Code / Copilot (.vscode/mcp.json, or MCP: Open User Configuration) — the key is servers, not mcpServers

{ "servers": { "nekoro-browser": { "command": "nekoro-browser-mcp" } } }

Prefer not to install anything up front? Replace the command with uvx, which fetches and runs on demand the way npx -y does — e.g. "command": "uvx", "args": ["--from", "nekoro-browser", "nekoro-browser-mcp"]. That only removes the install step for the MCP server; the daemon still has to be installed and running.

Restart the client afterwards. If the tools don't show up, run nekoro-browser --doctor first — a dead daemon looks exactly like a broken MCP config — then check the client's MCP log (Claude Desktop keeps them in ~/Library/Logs/Claude on macOS, %APPDATA%\Claude\logs on Windows).

What you get beyond the tool list: two escape hatches ship as tools — cdp (raw CDP command) and exec_python (arbitrary Python in the daemon namespace, so a whole multi-step flow costs one round trip). Screenshots come back as image content so clients render them inline. A helper's own failure ({"ok": false}) is surfaced as isError instead of being dressed up as success. And when you navigate to a site you have notes or scripts for, they ride along in the tool result — see Self-Healing and Site Knowledge.

API

Architecture

flowchart TD
    A["Chrome tab — your profile, your logins"]
    B["Extension background.js<br/>chrome.debugger / CDP"]
    C["Python daemon<br/>127.0.0.1:28417"]
    D["CLI<br/>nekoro-browser"]
    E["MCP server<br/>nekoro-browser-mcp"]

    A <-->|CDP| B
    B <-->|persistent WebSocket| C
    D -->|"HTTP /exec · token auth"| C
    E -->|"HTTP /exec · token auth"| C

Chrome extension (background.js) —— chrome.debugger / CDP
        ↕ persistent WebSocket
Python daemon (127.0.0.1:28417)
        ↕ HTTP /exec (token auth)
CLI (nekoro-browser)  ·  MCP server (nekoro-browser-mcp)

helpers.py (54 thin wrappers) → CDP commands, none of them aware of any particular website.

lifecycle.py manages the daemon: pid file + process fingerprint (avoids killing a reused pid), self-heal on stale daemon (CDP probe fails → auto cleanup and restart), localhost requests bypass the system proxy.

The extension is hardened against MV3 service worker eviction: a content_scripts heartbeat (an independent wake vector living in the page, reconnects and wakes the SW even after it's killed) + onStartup (reconnects instantly on Chrome cold start) + reattaches the last-driven tab after a restart instead of drifting to a blank tab.

Self-Healing and Site Knowledge

When an agent hits a gap it writes the missing piece and uses it immediately — nothing is recompiled, no daemon restart, no extension reload.

• src/nekoro_browser/agent_helpers.py is scratch paper: reloaded on every /exec, good for a quick experiment. It lives inside the installed package, so an upgrade overwrites it.
• Anything worth keeping goes in your own skills directory (NEKORO_DOMAIN_SKILLS, falling back to domain-skills/ in the repo), one folder per site holding both kinds of material: <site>/*.md for knowledge and <site>/*.py for workflows. Scripts are loaded into the /exec namespace on every call and can use the built-in helpers directly.

The point is that this material finds the agent instead of waiting to be discovered. navigate() and new_tab() return two extra fields when the site has any:

{'ok': True, 'loaded': True,
 'notes':   ['example/search.md — Example — search results'],
 'actions': ['open_first_result(query) — search and open the top hit']}

notes lists titles only — full text on every navigation would turn a one-time write into a permanent read cost. actions lists functions that are already callable, so the agent runs one instead of rebuilding the flow. list_site_actions() shows everything loaded, including files that failed to load. Conventions for what to record — and what not to — are in domain-skills/README.md.

The same idea applies to tabs. A tab left over from last time is still the same tab — its login and page state are intact — so new_tab() adds an existing field when the managed group already holds tabs for that site:

{'ok': True, 'tabId': 42, 'loaded': True,
 'existing': {'hint': 'switch_tab(id) reuses an open tab, or new_tab(url, reuse=True)',
              'tabs': [{'tabId': 17, 'title': 'Example Domain'}]}}

The tab is still opened — the field only makes reuse visible at the moment a duplicate is about to appear. Pass reuse=True to navigate an existing tab instead of opening one. Nothing is ever closed automatically: whether a tab is clutter or an asset is the user's call, so sweep_tabs() only reports candidates (same-site duplicates, stray about:blank) and sweep_tabs(dry_run=False) / close_tabs([...]) act on them. The active tab is never a candidate.

Platform Support

Known Limitations

• Unpacked extensions get disabled by Chrome. An extension installed via "Load unpacked" may be switched off automatically after a Chrome update or restart, or hidden behind the "Disable developer mode extensions" prompt. When --doctor reports Extension/SW not responding, re-enable it in chrome://extensions/ first. This project is not published to the Chrome Web Store, so the limitation is not going away soon.
• Service worker keepalive is not 100%. MV3 eviction timing is Chrome's call. The heartbeat + onStartup + reattach cover the vast majority of cases, but unattended long-running cron jobs should still health-check with --doctor and retry.
• Everything is anchored to one active tab. 16 helpers (click, click_selector, state, wait_selector, fill_input, …) take an explicit tab=id to target another already attached tab — naming a tab that is not attached is an error, never a silent fallback to the active one. The other 37 always follow the active tab, and there are still no parallel sessions: one daemon drives one Chrome, requests are serialised.
• Downloads land wherever Chrome is configured to put them, and the path cannot be changed from here. wait_for_download() returns {url, filename, bytes} — a filename, not a full path. Both Browser.setDownloadBehavior (-32601) and the deprecated Page.setDownloadBehavior (-32000 "Cannot not access browser-level commands") are browser-level and get rejected under chrome.debugger's tab attach, which only ever hands out a tab target. Set the directory in Chrome's own settings.
• The MCP server handles requests serially. During a wait_selector(timeout=90) every other request on that connection (including ping) queues behind it. Open separate client connections if you need concurrency.

Reference

Feedback

Hit a problem, or missing a helper you need? Open an issue. For bugs, include the output of nekoro-browser --doctor, your Chrome version and OS — saves a round trip.

PRs welcome. Run the tests first: for f in tests/test_*.py; do uv run python "$f"; done (CI runs them on all three platforms too).

Acknowledgments

Core architecture derived from:

• browser-harness — thin-wrapper philosophy (each function is a CDP alias, ≤10 lines), pipe mode, self-healing agent_helpers.py, domain-skills directory structure, cdp() raw access
• browser-act — state() indexed element tree, *[N] change markers, waitSelector() state polling, getMarkdown() page extraction
• Playwright — CDP Input.dispatchMouseEvent real mouse events (isTrusted:true), extension + daemon dual-path architecture

Ideas drawn from:

• ego-lite — "code base, not CLI base" (agent writes a script, not a command loop), unified locator syntax (css: / text: / xpath= …) with transient/permanent element-resolution errors as a retry/abandon signal (→ click()), "name says the intent" openOrReuseTab ergonomics (→ ensure_tab()), and experience-accumulation as a first-class design goal (nekoro's domain-skills already chase this)