Cobro MCP

What cobro-mcp MCP server does

The cobro-mcp MCP server links a human viewing a web page with an agent editing the corresponding project. The human opens a development URL in the controlled browser, activates pick mode, selects one or more elements or a region, writes a note, and presses Send. The agent receives the note alongside page information, element selectors, tag and class data, visible text, dimensions, selected styles, screenshots, console errors, and React source references when available.

The project source is not modified by the server itself. The agent uses the received context to make edits in the project. Cobro creates a .cobro/ directory for its state and screenshots. A browser toolbar and panel show working, completion, and navigation state to the person testing the page.

How it works

Register the MCP process with a compatible host. The host starts it for a session, and the server launches or reuses a browser window when the agent calls open(url). The page receives the overlay, while a local WebSocket carries interaction data and agent status between the browser and MCP process.

The normal loop is open, wait, edit the source, status, done, and then wait again. wait blocks until the person sends a note; a pending result means it should be called again. Multiple page drafts can be queued and delivered in order. status can identify the batch being edited, and done can refresh the page and highlight the changed selectors. close ends the browser session and cancels a pending wait.

The browser can follow the batch currently being handled. If the person navigates elsewhere during that work, the toolbar can provide a link back to the relevant path when processing finishes. Drafts with notes can be restored after a browser restart, while drafts without notes are discarded when the session closes.

Setup and configuration

Install the published package through the host’s stdio registration command:

claude mcp add -s user cobro -- npx -y cobro-mcp@latest

The same run command can be registered with other MCP hosts. A user-scoped registration makes the server available across repositories on that machine; a folder-scoped registration limits it to the current project. State is stored per repository in .cobro/, while the browser profile is shared at ~/.cobro/profile/.

Chrome or Edge is required. If neither is installed, install Playwright’s Chromium build and set COBRO_BROWSER_CHANNEL=chromium. To run from source, clone the repository, install dependencies, build with npm run build, and start dist/server.js; the build must be repeated after source changes because dist/ is not tracked.

Tools and capabilities

The cobro-mcp MCP server exposes six fixed tools:

• open launches the browser, navigates to a URL, and enables the overlay.
• wait receives the next human-submitted batch or reports that it is still pending.
• status displays progress and can move the browser to a batch’s page.
• done completes one or more batches, applies the refresh strategy, and highlights selected elements.
• screenshot saves a full-screen image or a cropped image around a selector.
• close cancels waiting, closes the browser, and removes drafts without notes.

The overlay supports single-element selection, grouped selections, region selection, queued drafts across pages, draggable toolbar and panel positions, theme choices, and configurable refresh behavior. The exact agent workflow is supplied to the host through MCP instructions when the server is registered.

Limitations and notes

Cobro is focused on browser observation and agent feedback; it does not add arbitrary observation or control tools beyond its six fixed tools. Pair it with another MCP server if the agent needs capabilities outside this workflow. The browser can be closed by the user, in which case wait may return browserGone: true and the agent must start again with open.

The server does not replace the project’s development server. Start the application separately, then provide its URL to open. In Claude Code, long waits move to the background after two minutes by default; CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS can shorten that interval through Claude Code settings.