Oculo

AI-Powered Native Browser

Website · Download · Quick Start · MCP Tools · Contributing

---

Cursor : VSCode :: Oculo : Chrome

Open-source AI browser that gives Claude Code, Cursor, Windsurf, and any MCP client the ability to see and interact with any website. 12 tools, under 300 tokens per flow.

Why Oculo?

	Feature
Native browser	Full Chromium engine -- not a wrapper, extension, or headless scraper
12 MCP tools	page, act, fill, read, run, media, shell, tabs, research, preview, translate, lens
< 300 tokens/flow	Compact responses by default -- cheaper than screenshot-based approaches
Self-healing automation	Selector caching + DOM diffing -- 44%+ faster on repeated workflows
Multi-provider AI	Built-in chat with Claude, OpenAI, Gemini, Grok, OpenClaw, Ollama
4-level security	auto / notify / confirm / blocked permission gate on every action
OS keychain vault	Credentials encrypted via electron.safeStorage (macOS Keychain / Windows DPAPI)
PII redaction	Credit cards, SSNs, JWTs, API keys, Bearer tokens stripped from all MCP responses
Anti-injection	Content boundary markers + regex-based injection detection
19 stealth patches	Navigator, WebGL, canvas, WebRTC, audio, font, battery, screen fingerprint defenses
Headless mode	Run without UI -- Docker support included
Cross-platform	macOS, Windows, Linux
Python SDK	pip install oculo -- sync and async clients

Quick Start

Download

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

git clone https://github.com/xidik12/oculo.git
cd oculo
npm install
npm run dev

Register with Claude Code

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

Register with Cursor / Windsurf

Add to your MCP config (.cursor/mcp.json or equivalent):

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

Tools are always discoverable (static definitions in the bridge), but Oculo must be running for tool calls to succeed.

12 MCP Tools

Tool	What it does	Token cost
page	Describe current page -- headings, forms, buttons, links. Supports compact, a11y (ref-tagged), and markdown modes	~30-80
act	Navigate, click, hover, scroll, type, press keys, login via vault, manage tabs, cookies, proxy, recording	~1 line
fill	Fill form fields by label/placeholder matching, optional submit. Handles text, select, checkbox, contenteditable	~1 line
read	Extract structured data -- search results, tables, lists, articles	compact
run	Multi-step pipeline with conditionals (page/act/fill/read/wait/if). Cached for replay	header + last
media	Generate images (Nano Banana 2 / DALL-E 3) or videos (Veo 3.1). Image-to-image editing	file path
shell	Execute shell commands non-interactively (ls, npm, git, python, etc.)	stdout+stderr
tabs	List all open browser tabs with URLs and titles	compact
research	Deep web research -- opens multiple tabs, reads pages, synthesizes findings	synthesized
preview	Pre-fetch a URL without navigating away from the current page	page description
translate	Translate page content or specific text to any language	translated text
lens	Visual analysis of the current page via screenshot + AI vision	description

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

Example Flows

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
  3. act({action: "navigate", url: "https://github.com/xidik12/oculo"})
  4. act({action: "click", text: "Star"})

Total: 4 tool calls, <100 tokens 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
  3. fill({fields: {"Name": "...", "Email": "..."}, submit: true})

Total: 3 tool calls

Headless Mode

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

# Via convenience script
node bin/oculo-headless.mjs

# Or with flags
npx electron . --headless
npx electron . --headless --headless-auto-approve   # auto-approve CONFIRM actions

# Environment variable
OCULO_HEADLESS=1 npm run dev

Docker

docker compose up

The included Dockerfile and docker-compose.yml run Oculo headless in a container with Xvfb.

Python SDK

from oculo import OculoClient

# Auto-discovers port from ~/.oculo-port
client = OculoClient()

# Describe the page
print(client.page())

# Navigate
client.act("navigate", url="https://example.com")

# Fill a form
client.fill({"Email": "hi@oculo.com", "Message": "Hello!"}, submit=True)

# Extract data
results = client.read("search results", format="json")

Async version available:

from oculo import AsyncOculoClient

async_client = AsyncOculoClient()
await async_client.act("navigate", url="https://example.com")

Install from the SDK directory:

pip install oculo

Architecture

Claude Code / Cursor / Windsurf
        |
        | stdio (MCP protocol)
        v
  bin/oculo-mcp.mjs            <-- stdio-to-HTTP bridge
        |
        | HTTP POST :19516/mcp (auth token)
        v
  McpServerManager              <-- Electron main process
        |
        | IPC
        v
  Renderer (React 19)           <-- Chromium process
        |
        | webview.executeJavaScript()
        v
  <webview> tags                <-- Actual web pages

Why HTTP instead of stdio? Electron's <webview> is only accessible from the renderer process. The main process (where stdio lives) can't touch page content. The HTTP bridge solves this via main-to-renderer IPC.

Port discovery: Oculo writes port:authtoken to ~/.oculo-port on startup. The bridge reads this file automatically.

Security

Permission Levels

Level	Actions	Behavior
Auto	navigate, page, read, scroll, screenshot, back, forward, reload, hover, listTabs, switchTab, preview, translate, lens	Executes silently
Notify	click, type, fill, select, press, submit, newTab, closeTab	Executes + OS notification
Confirm	payment, delete_account, change_password, send_email, download, oauth, shell, evaluate, setProxy, startRecording	Native dialog approval required
Blocked	read_vault, export_cookies, export_tokens, disable_security	Always rejected

Credential Vault

• Encrypted with electron.safeStorage (OS Keychain on macOS, DPAPI on Windows)
• Passwords never returned via IPC or MCP -- only domain + username exposed
• act({action: "login", site: "github.com"}) retrieves and fills credentials automatically

PII Redaction

All MCP responses pass through a redactor before reaching the AI client. Stripped patterns: credit card numbers, SSNs, JWTs, API keys, private keys, Bearer tokens.

Anti-Injection

MCP content is wrapped in boundary markers. Regex-based detection blocks prompt injection attempts embedded in page content.

Stealth (19 patches)

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

Self-Healing Automation

After successful act or fill calls, element selectors are cached with stability scores:

Selector type	Score
id	10
data-testid	10
aria-label	9
role + name	8
text	7
css	5

On subsequent runs, DOM diffing determines the strategy:

• > 80% similarity -- replay from cache (no LLM call needed)
• 50-80% -- fallback to alternative selectors
• < 50% -- re-engage AI for fresh resolution

AI Providers

Built-in chat panel supports multiple providers:

Provider	Auth	Models
Claude	API Key or CLI subscription	Opus, Sonnet, Haiku
OpenAI	API Key or Codex CLI	GPT-4o, GPT-4o mini, o1, o3
Gemini	API Key	2.0 Flash, 1.5 Pro, 1.5 Flash
Grok	API Key	Grok 2, Grok 2 Mini
Ollama	Local (no key)	Any pulled model
OpenClaw	API Key	OpenClaw models

Building

# Production build
npm run build

# Platform distributables
npm run dist:mac      # macOS DMG + ZIP
npm run dist:win      # Windows NSIS + portable
npm run dist:linux    # Linux AppImage + deb

# Other commands
npm run typecheck     # TypeScript checking
npm run lint          # ESLint
npm run test          # Vitest
npm run clean         # Remove build artifacts

Prerequisites

• Node.js 20+
• npm (not pnpm/yarn -- native modules require npm)
• macOS, Windows, or Linux

Project Structure

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 (port 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 new MCP tools.

Donate

If Oculo saves you time, consider supporting development:

BTC: 12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B

License

MIT

---

Built by Salakhitdinov Khidayotullo | getoculo.com