Oculo

[Oculo — an open-source AI browser that gives Claude Code, Cursor, Windsurf, and any MCP client eyes on the live web. A sample agent flow turns the request 'Log into GitHub and star the oculo repo' into four act tool calls that log in via the credential vault and click Star, using under 100 tokens.]

[GitHub stars] [Latest release] [Electron 34] [TypeScript 5.7] [React 19] [12 MCP tools] [MIT License]

Website · Download · Quick Start · MCP Tools · Architecture · Contributing

Oculo is a full-Chromium desktop browser that speaks the Model Context Protocol. Point Claude Code, Cursor, Windsurf, or any MCP client at it and your agent can see and drive real web pages — read the DOM, click, fill forms, extract data, run multi-step pipelines — through 12 compact tools that answer in under 300 tokens per flow.

Cursor : VSCode :: Oculo : Chrome

See it in action

Your agent describes intent; Oculo resolves it into a few tiny tool calls and hands back terse, redacted results — not megabytes of screenshots.

You: "Log into GitHub and star the oculo repo"
Claude Code calls:  1. act({action: "navigate", url: "https://github.com/login"})  2. act({action: "login", site: "github.com"})         # vault lookup, password never leaves the OS keychain  3. act({action: "navigate", url: "https://github.com/xidik12/oculo"})  4. act({action: "click", text: "Star"})
→ 4 tool calls, <100 tokens of response

You: "Fill out the contact form on example.com"
Claude Code calls:  1. act({action: "navigate", url: "https://example.com/contact"})  2. page()                                               # see the form structure  3. fill({fields: {"Name": "...", "Email": "..."}, submit: true})
→ 3 tool calls

Oculo runs a real Chromium engine on your machine and adds an agent-first control layer on top. That combination is the point:

Each tool does one thing and returns the smallest useful answer. Token cost is the response size the agent pays for.

Bonus: webmcp_list and webmcp_call discover and invoke page-declared tools via the WebMCP protocol.

[Architecture pipeline: an MCP client (Claude Code, Cursor, Windsurf) speaks stdio to the oculo-mcp bridge, which forwards over authenticated HTTP on port 19516 to the Electron main process, which sends IPC to the React renderer, which runs executeJavaScript inside the webview holding the live web page. Tools stay discoverable when idle; Oculo must be running to execute; port and token are published to ~/.oculo-port.]

Why HTTP instead of stdio? Electron's <webview> is only reachable from the renderer process. The main process — where stdio lives — can't touch page content. The HTTP bridge crosses that boundary via main-to-renderer IPC.

Port discovery. On startup Oculo writes port:authtoken to ~/.oculo-port. The bin/oculo-mcp.mjs bridge reads it automatically, so tool definitions stay discoverable even when the app is closed — only execution requires Oculo to be running.

1. Install

Grab the latest build from Releases, or run from source:

git clone https://github.com/xidik12/oculo.gitcd oculonpm installnpm run dev

2. Register with your MCP client

Claude Code

claude mcp add oculo -- node ~/oculo/bin/oculo-mcp.mjs

Cursor / Windsurf — add to your MCP config (.cursor/mcp.json or equivalent):

{  "mcpServers": {    "oculo": {      "command": "node",      "args": ["/path/to/oculo/bin/oculo-mcp.mjs"]    }  }}

3. (Optional) Headless & Docker

Run without a visible window for CI/CD, scraping, or server-side automation:

node bin/oculo-headless.mjs                          # convenience launchernpx electron . --headless                            # or raw flagsnpx electron . --headless --headless-auto-approve    # auto-approve CONFIRM actionsOCULO_HEADLESS=1 npm run dev                          # or via env var
docker compose up                                    # containerized headless (Xvfb)

4. (Optional) Python SDK

pip install oculo

from oculo import OculoClient
client = OculoClient()                 # auto-discovers port from ~/.oculo-portprint(client.page())                   # describe the pageclient.act("navigate", url="https://example.com")client.fill({"Email": "[email protected]", "Message": "Hello!"}, submit=True)results = client.read("search results", format="json")

An async AsyncOculoClient with the same surface is also available.

Every action passes through a permission gate, and every response is redacted before it reaches the model.

Permission levels

Credential vault

• Encrypted with electron.safeStorage → OS Keychain (macOS) / DPAPI (Windows).
• Passwords are never returned via IPC or MCP — only domain + username are exposed.
• act({action: "login", site: "github.com"}) retrieves and fills credentials without the model ever seeing them.

Redaction & anti-injection

• Every MCP response passes through a redactor that strips credit-card numbers, SSNs, JWTs, API keys, private keys, and Bearer tokens.
• Page content handed to the model is wrapped in boundary markers, and regex-based detection blocks prompt-injection attempts embedded in that content.

Stealth (19 patches)

Navigator (webdriver, languages, plugins, mimeTypes, connection, hardwareConcurrency, deviceMemory), window (chrome API, dimensions), WebGL (vendor/renderer spoofing), canvas (per-call fingerprint randomization), WebRTC (IP-leak prevention), AudioContext, font enumeration blocking, Battery API, and screen-resolution randomization.

Self-healing automation

After a successful act/fill, selectors are cached with stability scores — id and data-testid = 10, aria-label = 9, role+name = 8, text = 7, css = 5. On the next run, DOM diffing picks the strategy:

• > 80% similarity — replay from cache, no LLM call.
• 50–80% — fall back to alternative selectors.
• < 50% — re-engage the AI for a fresh resolution.

That's where the 44%+ speed-up on repeated workflows comes from.

Built-in AI chat

Oculo also ships a side-panel chat that talks to multiple providers directly:

Building from source

npm run build          # production buildnpm run dist:mac       # macOS DMG + ZIPnpm run dist:win       # Windows NSIS + portablenpm run dist:linux     # Linux AppImage + deb
npm run typecheck      # TypeScriptnpm run lint           # ESLintnpm run test           # Vitest

Prerequisites: Node.js 20+, npm (not pnpm/yarn — native modules require npm), macOS / Windows / Linux.

src/  main/                    Electron main process    ai/agent.ts            Multi-provider AI controller    captcha/               CAPTCHA detection + solvers    data/                  Bookmarks, downloads, history, session recording    engine/                Page describer, extractor, form-detector, pipeline, resolver,                           selector-cache, dom-differ, tab-manager    mcp/server.ts          HTTP MCP server (ports 19516–19520, auth token)    mcp/tools/             act, fill, page, read, run tool handlers    network/proxy.ts       HTTP/SOCKS proxy manager    security/              Vault, permissions, redactor, audit, anti-injection  preload/index.ts         contextBridge API  renderer/    App.tsx                Root browser UI component    components/            TabBar, AddressBar, ChatPanel, WebViewContainer,                           bookmarks, downloads, find, history, layout, common  shared/                  Types, constants, IPC channels, AI provider definitionsbin/  oculo-mcp.mjs            stdio-to-HTTP MCP bridge (for Claude Code / Cursor)  oculo-headless.mjs       Headless mode launchersdk/python/                Python SDK (pip install oculo)Dockerfile                 Container deploymentdocker-compose.yml         Docker Compose for headless mode

Contributing

See CONTRIBUTING.md for development setup, architecture details, and how to add a new MCP tool.

Donate

If Oculo saves you time, you can support development — BTC: 12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B

License

MIT © 2026 Salakhitdinov Khidayotullo

Built by Salakhitdinov Khidayotullo · getoculo.com