The recent Chrome 136 update introduced a significant hurdle for browser automation enthusiasts: the –remote-debugging-port flag now refuses to work with the default user profile. This change, aimed at enhancing security, means that traditional automation tools relying on Chrome DevTools Protocol (CDP) connections launch a fresh browser instance devoid of your logged-in sessions, cookies, and personalized extensions. For developers and testers who depend on automating tasks within their authenticated web environments—such as managing social media accounts, testing enterprise SaaS platforms, or scraping data from personalized dashboards—this forces disruptive workflows. Users must either sacrifice their session state, resort to cumbersome profile management, or abandon automation altogether. This limitation exposed a critical gap in the tooling landscape, demanding a solution that operates within the constraints of modern browser security while preserving the user’s existing browser context.
Enter nekoro-browser, a lightweight CLI and MCP server designed specifically to circumvent this Chrome 136 restriction by leveraging the chrome.debugger API through a browser extension. Unlike raw CDP connections that require a debug port, an extension’s chrome.debugger API is exempt from the same-origin restrictions that block remote debugging on the default profile. This architectural choice allows nekoro-browser to attach to your existing Chrome instance—complete with all logged-in states, active extensions, and browser settings—without launching a new process. The tool consists of three core components: a minimal Chrome extension that exposes debugging capabilities, a local MCP (Model Context Protocol) server daemon facilitating communication, and a CLI client that sends automation commands. By operating within the extension framework, nekoro-browser maintains compatibility with Chrome’s evolving security model while delivering a seamless automation experience that feels native to the user’s browsing environment.
Understanding why traditional methods fail requires examining Chrome’s security evolution. Starting with version 136, Google tightened restrictions on the –remote-debugging-port argument to prevent malicious websites or extensions from silently attaching to and controlling a user’s primary browser session via debugging interfaces. When specified, Chrome now ignores the flag if it points to the default profile, forcing developers to use a separate, clean profile for debugging. While this enhances user protection against certain attack vectors, it inadvertently breaks legitimate automation workflows that rely on persistent sessions. Workarounds like launching Chrome with –user-data-dir or creating a new profile introduce friction: users lose access to their bookmarks, history, saved passwords, and active logins, making automation feel detached from real-world usage. This paradigm shift necessitates tools that work *with* Chrome’s security model rather than against it, a niche nekoro-browser fills by utilizing the sanctioned extension debugging pathway.
nekoro-browser’s architecture is elegantly minimalist yet powerful. The Chrome extension, once loaded, remains dormant until the MCP daemon initiates a connection via the chrome.debugger API. This extension acts as a bridge, translating high-level automation commands (like navigating to a URL or clicking an element) into low-level debugger actions that operate within the context of the active tab. The MCP daemon, written in Python with zero third-party dependencies, listens on a local TCP port (default 28417) and communicates with the extension using a secure token-based authentication mechanism. Crucially, the daemon does not launch Chrome itself; it assumes Chrome is already running with the extension loaded. This design ensures zero overhead on browser performance during idle periods and eliminates the need to manage browser processes—a stark contrast to tools like Selenium that spawn and manage their own driver instances. The CLI client then sends simple, human-readable commands to the daemon, which relays them to the extension for execution in the user’s actual browser session.
Getting started with nekoro-browser is intentionally straightforward to lower the barrier to adoption. The project targets Python 3.12+ and requires no external dependencies beyond the standard library, simplifying installation across environments. Users can install it globally via pipx with a single command: `pipx install nekoro-browser`, which creates an isolated environment and exposes the `nekoro-browser` executable. For those preferring traditional pip, the command `pip install nekoro-browser` works equally well. Developers interested in contributing or experimenting with the latest features can clone the repository from GitHub, navigate into the directory, and perform an editable install using `uv pip install -e .` (or `pip install -e .` if uv isn’t available). This flexibility ensures accessibility whether you’re a casual user seeking quick automation or a developer integrating the tool into complex workflows, all while maintaining a clean, dependency-free footprint.
After installation, loading the extension is a critical one-time setup step. Users must open Chrome and navigate to `chrome://extensions`, enable “Developer mode” in the top-right toggle, then click “Load unpacked” and select the extension directory located within the nekoro-browser installation (typically found in the package’s data files). The extension is lightweight, requesting only essential permissions: access to tabs, debugging capabilities, and storage for the authentication token. Once loaded, it appears in the extensions menu as “nekoro-browser” and remains passive until activated by the daemon. Importantly, the extension does not inject scripts into web pages or alter page behavior during normal browsing—it only activates when the daemon sends a debugging command. This design ensures it poses no performance overhead or security risk during everyday use while standing ready to facilitate automation tasks on demand.
Driving the browser through the terminal reveals nekoro-browser’s user-centric design philosophy. Upon starting the daemon (via `nekoro-browser-mcp` or the CLI’s serve command), users gain access to a suite of 53 intuitive tools designed to minimize guesswork in element interaction. The standout feature is the `state()` function, which analyzes the current page and assigns a unique, sequential number to every interactive element—buttons, links, inputs, and more—visible in the viewport. This eliminates the need to craft fragile CSS selectors or XPath expressions that break with minor UI changes. To click an element, users simply call `click_index(n)` where `n` corresponds to the number shown by `state()`. For example, after running `state()` and seeing “3” next to a login button, executing `click_index(3)` triggers a click on that button. This approach mirrors how humans visually interact with pages, making automation scripts more resilient, readable, and maintainable—especially valuable for AI-assisted coding where precise selector generation remains challenging.
Integration with AI-powered development tools represents a significant advancement in nekoro-browser’s utility. The tool implements the Model Context Protocol (MCP) standard, allowing it to expose its browser automation capabilities as discoverable resources to AI assistants like Claude Desktop, Opus, and Codex. Configuration varies slightly per platform but follows a consistent pattern: the command to invoke is always `nekoro-browser-mcp`, while the configuration file structure adapts to the host tool’s expectations. For Claude Desktop, users edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) to add an MCP server entry. Opus users modify their `opencode.json` file, specifying the command as an array under the `mcp` key. Codex users can either add a server via `~/.codex/config.toml` or use the CLI command `codex mcp add nekoro-browser — nekoro-browser-mcp`. Once configured, the AI assistant can directly invoke browser actions—like navigating to a URL, extracting text, or filling forms—through natural language prompts, enabling powerful workflows where AI reasons about web content and executes steps within the user’s authenticated session.
Security and privacy are foundational to nekoro-browser’s design, addressing inherent risks in exposing local browser control. The MCP daemon binds exclusively to `127.0.0.1` (localhost), ensuring it is inaccessible from external networks or other users on the same machine. Communication is secured by a randomly generated authentication token stored in a file readable only by the current user (emulating `chmod 600` permissions). Before accepting any connection, the daemon validates that the presenting token matches this file. Critically, the `/exec` endpoint—which allows execution of arbitrary Python code for advanced use cases—is protected by this same token mechanism, meaning only processes running under the user’s account can leverage it. This same-user boundary prevents privilege escalation attacks while allowing legitimate local tools (like IDEs or AI assistants) to interact securely. The extension itself only accepts commands from the verified daemon, creating a closed-loop trust model that aligns with OS-level user isolation principles, significantly reducing the attack surface compared to tools that open debug ports to all local processes.
Positioning nekoro-browser within the broader browser automation ecosystem highlights its unique value proposition. Traditional tools like Selenium, Playwright, and Puppeteer excel at cross-browser testing and headless automation but inherently require launching browser instances—either new profiles or via debug ports—that now conflict with Chrome 136’s default profile restrictions. While these tools offer robust feature sets for synthetic testing, they fall short when automation must occur within a user’s genuine browsing context. nekoro-browser carves out a distinct niche by focusing exclusively on automating the *user’s existing* Chrome session, making it ideal for tasks where session fidelity is paramount: automating personalized news feeds, interacting with internal company portals requiring SSO, managing multi-factor authentication workflows, or extracting data from dynamic web applications that rely heavily on client-side state. It complements rather than replaces full-testing suites, serving as a specialized tool for attended automation scenarios where preserving the user’s state is non-negotiable.
Practical application scenarios illuminate where nekoro-browser delivers tangible benefits. Consider a marketing professional needing to daily extract engagement metrics from Twitter’s analytics dashboard—a process requiring login and navigating through multiple AJAX-driven views. Traditional automation would force re-login each run, risking rate limits or CAPTCHAs. With nekoro-browser, a simple script can `state()` the dashboard, `click_index()` on the date range selector, input new values via `type_index()`, and `screenshot()` the results—all within the user’s persistent session. Similarly, QA engineers testing a banking portal can automate navigation through authenticated transaction histories without re-entering credentials after every test run. Limitations include Chrome-only current support (though Chromium-based browsers like Edge or Brave may work if they support extensions) and the requirement that Chrome must be running with the extension loaded beforehand. For cross-browser testing, teams should still leverage Playwright or Selenium, reserving nekoro-browser for session-critical attended tasks where human supervision is feasible.
Adopting nekoro-browser effectively involves integrating it into your existing automation strategy with clear boundaries. Use it for scripts that benefit from or require the user’s logged-in state—such as personal productivity bots, internal tool automation, or supervised data harvesting sessions. Avoid using it for large-scale, unattended load testing or cross-browser compatibility checks where traditional tools remain superior. Keep the extension updated via periodic reinstalls from the source to capture security patches and feature improvements. When writing scripts, leverage the `state()`/`click_index()` paradigm for robustness, and supplement with text-based tools like `get_text_index()` or `get_attribute_index()` for validation. Remember that the daemon assumes Chrome is already running; consider wrapping automation routines in a helper that checks for Chrome’s presence and prompts the user to launch it if needed. This mindful application ensures you harness nekoro-browser’s strengths while mitigating its inherent constraints.
The nekoro-browser project exemplifies how thoughtful engineering can adapt to evolving platform constraints while solving real user pain points. By embracing Chrome’s extension debugging API as a sanctioned automation vector, it turns a restrictive security update into an opportunity for more user-centric tooling. Its lightweight, dependency-free design respects developer environments, and the MCP integration bridges the gap between browser automation and the rapidly advancing AI assistant landscape. As browser vendors continue to tighten security around debugging interfaces, approaches that operate within extension frameworks—like nekoro-browser—are likely to gain prominence for attended automation tasks. The MIT license ensures freedom to use, modify, and distribute, fostering community-driven enhancements that could expand functionality or browser support in the future.
To experience nekoro-browser firsthand, begin with installation: run `pipx install nekoro-browser` (ensuring Python 3.12+ is available). Next, load the extension via Chrome’s extensions page as described. Start the daemon in a terminal window with `nekoro-browser-mcp` (or `nekoro-browser serve`), then in another terminal, experiment with basic commands: try `nekoro-browser state` to see numbered elements on your current tab, followed by `nekoro-browser click_index 1` to interact with the first detectable item. For AI-assisted workflows, configure your preferred assistant using the platform-specific MCP guidelines—Claude Desktop users should verify the config file path and restart the application after editing. As you build more complex automations, consult the SKILL.md documentation in the repository for detailed tool references. The project welcomes contributions; if you encounter issues or have ideas, fork the GitHub repo, run the test suite with `for f in tests/test_*.py; do uv run python “$f”; done`, and submit a pull request. In an era where browser security and automation needs often clash, nekoro-browser offers a practical path forward—keeping your digital workspace intact while putting repetitive tasks on autopilot.