# oculo

A full Chromium desktop browser that speaks MCP. Useful when your agent needs to click through live pages instead of parsing screenshots.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: xidik12
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/xidik12/oculo
- Updated: 2026-07-20
- HTML: https://affpapa.org/en/nevibecode/mcp/oculo

## What it does

Oculo is a desktop browser built on Chromium with a control layer for agents. Point Claude, Cursor, Windsurf or another MCP client at it, and the agent can read the DOM, click, fill forms and pull data off real pages. Responses come back as short text rather than megabytes of screenshots.

Twelve tools cover the work. `page` describes what is on screen, `act` handles navigation and clicks, `fill` matches fields by label or placeholder, `read` extracts tables and lists, `run` chains steps with conditionals. There is also `media` for image and video generation, `shell` for commands, and `research` for opening several tabs at once. Credentials sit in the OS keychain via `electron.safeStorage`, so a password never leaves it.

Oculo has to be running for any tool to execute. On startup it publishes the port and auth token to `~/.oculo-port`, and the `oculo-mcp` bridge reaches it over HTTP on port 19516. The reason is Electron's `<webview>`: only the renderer process can touch page content, and stdio lives in the main process.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add oculo -- npx -y oculo-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add oculo -- npx -y oculo-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "oculo": {
            "command": "npx",
            "args": [
                "-y",
                "oculo-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "oculo": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "oculo-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add oculo npx -y oculo-mcp
```

## When to use it
- log into a site and perform an action as the user
- fill out and submit a contact form
- scrape a table or list of results from a page
- run a multi-step flow across several tabs
- translate page content into another language

## Example prompts
- Log into github.com and star the xidik12/oculo repo
- Fill out the form at example.com/contact and submit it
- Collect every heading and link from the open page

## Similar
- [Kernel MCP Server](https://affpapa.org/en/nevibecode/mcp/kernel-mcp-server.md) — MCP server · ★ 38
- [fortress](https://affpapa.org/en/nevibecode/mcp/fortress.md) — MCP server · ★ 777
- [PageMap](https://affpapa.org/en/nevibecode/mcp/pagemap.md) — MCP server · ★ 36
- [browser-control](https://affpapa.org/en/nevibecode/skills/browser-control.md) — skill · 1000 installs
- [setup-browser-cookies](https://affpapa.org/en/nevibecode/skills/setup-browser-cookies.md) — skill · 342 installs
- [open-gstack-browser](https://affpapa.org/en/nevibecode/skills/open-gstack-browser.md) — skill · 318 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md