Oculo README

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.

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.git
cd oculo
npm install
npm 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 launcher
npx electron . --headless                            # or raw flags
npx electron . --headless --headless-auto-approve    # auto-approve CONFIRM actions
OCULO_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-port
print(client.page())                   # describe the page
client.act("navigate", url="https://example.com")
client.fill({"Email": "hi@oculo.com", "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 build
npm run dist:mac       # macOS DMG + ZIP
npm run dist:win       # Windows NSIS + portable
npm run dist:linux     # Linux AppImage + deb

npm run typecheck      # TypeScript
npm run lint           # ESLint
npm 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 definitions
bin/
  oculo-mcp.mjs            stdio-to-HTTP MCP bridge (for Claude Code / Cursor)
  oculo-headless.mjs       Headless mode launcher
sdk/python/                Python SDK (pip install oculo)
Dockerfile                 Container deployment
docker-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