oculo-mcp

oculo-mcp

MCP (Model Context Protocol) server for Oculo — the AI-powered native browser. This package connects any MCP client (Claude Code, Claude Desktop, Cursor, Windsurf) to a running Oculo instance via stdio transport.

Prerequisites

• Node.js >= 18
• Oculo browser must be running (download from getoculo.com)

Quick Start

Claude Code

claude mcp add oculo -- npx oculo-mcp

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "oculo": {
      "command": "npx",
      "args": ["-y", "oculo-mcp"]
    }
  }
}

Cursor / Windsurf

Add to your MCP settings:

{
  "oculo": {
    "command": "npx",
    "args": ["-y", "oculo-mcp"]
  }
}

Global Install (alternative)

npm install -g oculo-mcp

Then use oculo-mcp as the command instead of npx oculo-mcp.

How It Works

Oculo writes its port to ~/.oculo-port on startup. This bridge reads that file, speaks MCP over stdio, and forwards tool calls to Oculo's HTTP server. Tools are always discoverable (even when Oculo isn't running) — errors surface at call time with clear instructions.

Available Tools (16)

Tool	Description
page	Describe current page (compact, a11y tree, or markdown extraction)
act	Click, navigate, scroll, type, login, screenshot, and 50+ browser actions
fill	Fill form fields by visible label (text, select, checkbox, contenteditable)
read	Extract structured data (tables, lists, search results, articles)
run	Multi-step pipelines with conditionals — cached for replay
media	Generate images (Nano Banana / DALL-E 3) or videos (Veo 3.1)
shell	Execute shell commands non-interactively
tabs	List and manage open browser tabs
research	Deep web research across multiple tabs
preview	Pre-fetch a URL without navigating
translate	Translate page content or text
lens	Visual analysis via screenshot
abort	Cancel pending tool calls
status	List pending tool calls
webmcp_list	Discover WebMCP tools registered by the page
webmcp_call	Call a WebMCP tool from the page

Example Usage

Once connected, your AI assistant can:

"Navigate to github.com and star the oculo repo"
"Fill out the contact form on this page"
"Extract all product prices from this table"
"Take a screenshot and describe what you see"
"Research the latest news about AI browsers"

Troubleshooting

Issue	Solution
"Oculo browser is not running"	Launch the Oculo app first
"Connection refused"	Oculo may have crashed — restart it
Stale port file	The bridge auto-cleans ~/.oculo-port if Oculo isn't responding
Tools show but calls fail	Make sure Oculo is in the foreground with a page loaded

Links

• Website: getoculo.com
• Source: github.com/xidik12/oculo
• Issues: github.com/xidik12/oculo/issues
• MCP Directory: mcp.so

License

MIT