Browser automation has long been a double-edged sword for developers and QA engineers. Traditional tools like Selenium or Playwright often require launching a separate browser instance, which means starting from a clean slate—no cookies, no logged-in state, and no installed extensions. This forces teams to rebuild authentication flows for every test, adding complexity and slowing down feedback loops. Moreover, headless modes can hide visual bugs that only appear in a real user context. Enter nekoro-browser, a lightweight CLI and MCP server that drives the very Chrome instance you already use for daily work. By leveraging the Chrome extension’s access to the debugger API, it interacts with your existing browser profile, preserving logins, cookies, session storage, and even custom extensions. This approach eliminates the need for the infamous –remote-debugging‑port flag and sidesteps the overhead of managing duplicate browser binaries, offering a more authentic testing environment that mirrors actual user behavior.
At its core, nekoro-browser consists of two parts: a small Chrome extension that exposes a debug endpoint, and a Python‑based daemon that communicates with that endpoint over a local TCP socket. Once the extension is loaded into Chrome, the daemon can query the DOM, dispatch mouse and keyboard events, and navigate pages—all while staying within the security boundaries of your user profile. Because it talks directly to the browser you already have open, there is no need to launch a separate process or manage driver executables. The extension injects a minimal script that enables the debugger protocol, and the daemon translates high‑level commands like “click the fifth button” into the appropriate low‑level actions. This tight integration means that any state change—such as a login token being stored in localStorage—is instantly reflected in the browser you see, making debugging and iteration far more intuitive.
Getting started with nekoro-browser is deliberately frictionless. The project targets Python 3.12+ and intentionally avoids third‑party dependencies, keeping the installation footprint tiny. You can add it to your environment with a simple pipx install nekoro-browser, or, if you prefer uv, clone the repository and run uv pip install -e . from the source directory. The zero‑dependency promise reduces the risk of version conflicts in CI pipelines and makes it easy to embed in developer toolchains. Once installed, the only manual step is to load the provided Chrome extension from the browser’s extensions page (chrome://extensions). After that, the daemon can be started in the background with a single command, and it will announce its readiness via a short log message. This streamlined onboarding encourages teams to adopt the tool without wading through lengthy setup guides.
To verify that the daemon is ready, you simply open any regular webpage in Chrome—say, a blank tab or your internal dashboard—and then invoke the CLI’s status check. The daemon listens on localhost port 28417 by default, and a successful connection returns a JSON payload confirming that the extension is attached and responsive. Because the daemon binds exclusively to 127.0.0.1, external machines cannot reach it, which limits the attack surface to local users only. This design choice aligns with the principle of least privilege while still providing a convenient interface for scripts and AI agents running on the same workstation. Should you need to change the port—for example, to avoid a conflict with another local service—you can set the NEKORO_PORT environment variable before launching the daemon, offering flexibility without complicating the core workflow.
Interacting with the browser through nekoro-browser feels surprisingly natural, thanks to its element‑numbering abstraction. The state() function returns a JSON representation of the current page where every interactable element—buttons, links, inputs, etc.—is assigned a sequential index. Rather than wrestling with brittle CSS selectors or XPath expressions, you can call click_index(3) to activate the third element listed in the most recent state snapshot. Importantly, these indices are recomputed on each call to state(), so they automatically adapt to dynamic DOM changes such as those triggered by single‑page‑application frameworks. This eliminates a common source of flakiness in traditional selector‑based tests and empowers both human operators and AI models to reason about the UI in a straightforward, ordinal manner.
Beyond the CLI, nekoro-browser shines as a middleware for AI‑driven agent frameworks through its MCP (Model‑Control‑Protocol) server. The daemon exposes a standardized endpoint that agents can query to discover available tools—navigate, click, type, extract text, and more—then execute them via simple JSON‑RPC calls. Registering the service is uniform across platforms: you always reference the command nekoro-browser-mcp, while the surrounding configuration varies slightly depending on the host application. For Claude Desktop, you add an entry to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows). In opencode, the configuration lives in opencode.json with the command specified as an array under the mcp key. For Codex users, the ~/.codex/config.toml file or the codex mcp add nekoro-browser — nekoro-browser-mcp command achieves the same result. This uniformity lowers the barrier for agents to start controlling your browser without writing custom glue code.
Security considerations were front‑and‑center in nekoro-browser’s design. The daemon only accepts connections from the local loopback interface, ensuring that remote attackers cannot directly issue commands to your browser. Communication is protected by a token file that resides in a user‑specific directory and is readable only by the owning user (mode 600, akin to the browser‑harness project). This means that while other processes running under your own account can potentially interact with the daemon, any process executed by another user or a sandboxed container lacks the necessary permissions. The /exec endpoint, which allows arbitrary Python execution, is deliberately gated behind this token check, preventing privilege escalation scenarios. Overall, the threat model matches that of typical local developer tools: you trust code running under your own user, but you keep the doors closed to external intruders.
When compared to established automation suites, nekoro-browser occupies a distinctive niche. Selenium WebDriver depends on external drivers (chromedriver, geckodriver) and often requires launching a headless Chrome instance with a fresh profile, which means re‑authenticating for every test run. Playwright, while more modern, similarly spawns its own browser processes and relies on a WebSocket connection that must be established before each script. Puppeteer offers a similar experience, tightly coupling to a specific Chromium build. None of these preserve the user’s everyday browser state out of the box. Nekoro-browser, by contrast, works with the Chrome you already have open—complete with saved passwords, active sessions, and personalized settings—making it ideal for scenarios where context matters, such as testing a feature flag that depends on a user’s membership tier or reproducing a bug that only manifests after a series of intricate UI interactions.
The practical advantages of preserving login state extend beyond convenience; they translate into measurable gains in productivity and reliability. Developers can write end‑to‑end tests that start from an authenticated dashboard, bypassing the need to stub authentication APIs or fixture factories. QA engineers can reproduce customer‑reported issues exactly as they occurred, because the browser retains the same cookies, localStorage, and IndexedDB data that the user had at the time of the incident. Automation engineers tasked with repetitive workflows—such as uploading a monthly report to an internal portal—can script those actions without having to re‑enter credentials each time, reducing both manual effort and the risk of authentication‑related failures. Moreover, because the tool operates against the real browser renderer, any CSS‑specific quirks, font‑rendering differences, or extension‑induced behavior are faithfully captured, leading to fewer false‑negatives in test suites.
Looking at the broader market, nekoro-browser arrives at a moment when the intersection of large language models and browser automation is heating up. Agent frameworks like AutoGPT, BabyAGI, and the various copilots increasingly rely on the ability to perform web‑based tasks—filling forms, extracting information, navigating dashboards—yet they often grapple with the brittleness of selector‑based approaches and the overhead of spinning up isolated browsers. By providing a lightweight, local‑first interface that respects user privacy and existing sessions, nekoro-browser aligns with the emerging trend of “agent‑computer interfaces” that prioritize seamless, secure, and context‑aware interaction. Its MIT‑licensed, Python‑centric implementation also makes it easy to extend or embed in custom toolchains, inviting contributions from the open‑source community that values transparency and modularity.
To get the most out of nekoro-browser, consider a few practical tips. First, if you plan to run the daemon on a non‑standard port, export NEKORO_PORT=XXXX before launching; the extension does not need reconfiguration because it connects via the native debugger protocol, not the daemon’s port. Second, consult the SKILL.md file bundled with the project for a catalog of helper functions—such as wait_for_selector, get_text, and evaluate_js—that go beyond the basic state/click_index paradigm and can accelerate script development. Third, when contributing, run the test suite with the provided one‑liner: for f in tests/test_*.py; do uv run python “$f”; done. The project’s CI validates the code on Linux, macOS, and Windows, ensuring cross‑platform reliability. Finally, keep an eye on the extension’s version number; updates may introduce new debugger capabilities or security patches, and upgrading is as simple as re‑loading the extension in chrome://extensions.
In conclusion, nekoro-browser offers a compelling alternative to conventional browser automation by marrying the fidelity of your personal Chrome profile with the programmability of a modern CLI and MCP server. Its zero‑dependency install, preservation of login state, and intuitive element‑indexing model reduce friction for developers, QA, and AI agent builders alike. If you’re tired of rebuilding authentication flows for every test or frustrated by flaky selectors in headless environments, give nekoro-browser a spin. Install it, load the extension, start the daemon, and try a simple script that navigates to your favorite site, clicks a button using state() and click_index(), and prints the resulting text. As you grow comfortable, explore advanced helpers, integrate with your AI agent of choice, and consider sharing feedback or pull requests to help shape the future of this open‑source project. The browser you already love just got a lot more powerful—without sacrificing the session you rely on.