Oculo

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