# io.github.xidik12/oculo (npm · oculo-mcp)

AI-powered native browser with 12 MCP tools. ~30 tokens per page.

- Trust score: 66/100 (medium)
- Change this week: +42
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `oculo-mcp`: 66/100 (this document), [markdown](https://verifymcp.io/servers/xidik12-oculo/oculo-mcp.md), [page](https://verifymcp.io/servers/xidik12-oculo/oculo-mcp)

## Channel facts

- Registry: `npm`
- Package: `oculo-mcp`
- Version: `0.4.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 86/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 137 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 65/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 2226 tokens (~139/item across 16 items; 16 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add xidik12-oculo -- npx -y oculo-mcp
```

### Codex

```bash
codex mcp add xidik12-oculo -- npx -y oculo-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "xidik12-oculo": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "oculo-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add xidik12-oculo --command npx --arg -y --arg oculo-mcp
```

### Hermes

```yaml
mcp_servers:
  xidik12-oculo:
    command: "npx"
    args: ["-y", "oculo-mcp"]
```

### Other

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

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 66, +3)

- [functional improvement] Stability: unverified → 0.23

### 2026-08-02 (score 63, +36)

- [security regression] Provenance: fail → unverified
- [security regression] Install scripts: pass → unverified
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional regression] License: pass → unverified
- [functional regression] Maintenance: pass → unverified
- [functional improvement] Schema quality: unverified → good
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] MCP protocol: unverified → pass
- [functional] Licence: MIT

### 2026-08-01 (score 27, −16)

- [security regression] Known CVEs: partial → unverified
- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Capabilities: pass → unverified
- [functional regression] Dependency health: partial → unverified

### 2026-07-31 (score 43, −2)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-28 (score 45, +21)

- [functional regression] Security disclosure: unverified → fail
- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: unverified
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: fail

### 2026-07-27 (score 24)

First indexed and scored.

## MCP tools (16)

### `page` (~195 tokens)

Describe the current page in Oculo browser. Default: compact (~30-80 tokens). Use detail="a11y" for ref-tagged accessibility tree — interactive elements get [ref=e1],[ref=e2]... refs usable in act tool. Use detail="markdown" for full article content as clean markdown.

Input parameters:

- `detail` (string): compact (default ~30-80 tokens), a11y (ref-tagged accessibility tree ~200-500 tokens), or markdown (article extraction via Readability)
- `include` (array): What to include: "forms", "buttons", "links", "headings", "text", "images"
- `scope` (string): CSS selector to scope description to a section of the page
- `screenshot` (boolean): Attach a screenshot (default: false)
- `tabId` (string): Target a specific tab by ID (for parallel execution). Omit for active tab.

### `act` (~595 tokens)

Perform an action in Oculo browser: click, navigate, scroll, press key, hover, type, login. Elements found by ref (from a11y snapshot), text, role, label, placeholder, or CSS selector. After click/navigate/back/forward/reload, returns fresh ref-tagged snapshot. Use newTab with background=true to open tabs without switching, then use tabId to run actions in parallel.

Input parameters:

- `action` (string, required): Action to perform
- `amount` (number): Scroll amount in pixels
- `attribute` (string): Attribute name for getAttribute action
- `autoSubmit` (boolean): Auto-submit after login (default: true)
- `background` (boolean): For newTab: open in background without switching (default: false). Returns tab ID for parallel execution.
- `clear` (boolean): Clear existing content before typing (for type action). Works with both regular inputs and contenteditable fields.
- `content` (string): File content for writeFile action
- `cookies` (array): Cookies array for importCookies action
- `direction` (string): Scroll direction
- `expression` (string): JavaScript expression for evaluate action
- `from` (object): Drag source: {x, y} or {text, selector}
- `key` (string): Key to press (Enter, Tab, Escape, etc.)
- `label` (string): Label text associated with the element
- `modifiers` (array): Modifier keys (Ctrl, Shift, Alt, Meta)
- `name` (string): Accessible name of the element
- `nth` (number): Which match to use (0-indexed, default: 0)
- `placeholder` (string): Placeholder text of the input
- `proxy` (object): Proxy config for setProxy action: {type, host, port, username?, password?, bypass?}
- `ref` (string): Element ref from a11y snapshot (e.g. "e5"). Preferred over text/selector — use page({detail:"a11y"}) first.
- `role` (string): ARIA role (button, link, textbox, etc.)
- `screenshot` (boolean): Attach screenshot after action
- `selector` (string): CSS selector (fallback)
- `site` (string): Site domain for login action (uses credential vault)
- `tabId` (string): Target a specific tab by ID (for parallel execution). Omit for active tab.
- `text` (string): Visible text on the element to interact with
- `to` (object): Drag target: {x, y} or {text, selector}
- `url` (string): URL for navigate action
- `value` (string): Value for select action, file path for readFile/writeFile
- `x` (number): X coordinate for clickAtPoint/drag
- `y` (number): Y coordinate for clickAtPoint/drag

### `fill` (~129 tokens)

Fill form fields in Oculo browser by label, placeholder, or data-placeholder text. Handles text, select, checkbox, textarea, and contenteditable (DraftJS, ProseMirror). Use visible labels as keys.

Input parameters:

- `fields` (object, required): Object mapping field label → value (e.g. {"Email": "hi@oculo.com"})
- `screenshot` (boolean): Attach screenshot after filling
- `submit`: Submit form. true = first submit button, string = button text
- `tabId` (string): Target a specific tab by ID (for parallel execution). Omit for active tab.

### `read` (~127 tokens)

Extract structured data from the page in Oculo browser (search results, tables, lists, articles).

Input parameters:

- `fields` (array): Specific fields to extract
- `format` (string): Output format (default: text)
- `limit` (number): Max items to return (default: 10)
- `scope` (string): CSS selector to narrow extraction scope
- `tabId` (string): Target a specific tab by ID (for parallel execution). Omit for active tab.
- `what` (string, required): What to extract: "search results", "products", "table data", etc.

### `run` (~231 tokens)

PREFERRED for any task with 2+ actions. Executes a multi-step pipeline in a SINGLE call — use this instead of multiple act/fill calls. Example — post on X: run({steps:[{act:{action:"navigate",url:"https://x.com/compose/post"}},{wait:{timeout:2000}},{act:{action:"type",text:"Hello world",role:"textbox"}},{act:{action:"click",text:"Post",role:"button"}}]}). Each step is an object with exactly ONE key: page, act, fill, read, wait, or if. Cached for replay.

Input parameters:

- `description` (string): Short description for caching
- `returnAll` (boolean): Return results from all steps (default: false)
- `steps` (array): Array of steps. Each step is an object with exactly ONE key: page, act, fill, read, wait, or if.
- `tabId` (string): Target a specific tab by ID (for parallel execution). Omit for active tab.
- `workflow` (string): Replay a cached workflow by ID

### `media` (~204 tokens)

Generate images (Nano Banana 2 / DALL-E 3) or videos (Veo 3.1) via Oculo. Returns saved file path. Supports image-to-image editing with reference image.

Input parameters:

- `duration` (number): Video duration: 4, 6, or 8 seconds
- `image` (string): Path to reference image for image-to-image editing/transformation (Gemini only)
- `model` (string): Image model: nano-banana-2 (default), nano-banana-pro, nano-banana
- `prompt` (string, required): What to create
- `provider` (string): Override: gemini, openai, stability
- `size` (string): Image: 1024x1024, 2K, 4K. Video: 16:9, 9:16
- `style` (string): natural, vivid, cinematic, anime
- `type` (string, required): Generate an image or video

### `shell` (~72 tokens)

Execute a shell command (ls, npm, git, node, python, etc.) via Oculo and return stdout+stderr. Non-interactive only.

Input parameters:

- `command` (string, required): The shell command to execute
- `timeout` (number): Timeout in milliseconds (default: 30000, max: 120000)

### `webmcp_list` (~46 tokens)

Discover WebMCP tools registered by the current page via navigator.modelContext.registerTool() or <form toolname="..."> elements. Returns list of available page-declared tools.

### `webmcp_call` (~63 tokens)

Call a WebMCP tool registered by the current page. Use webmcp_list first to discover available tools.

Input parameters:

- `args` (object): Arguments to pass to the tool
- `name` (string, required): Tool name to call (from webmcp_list)

### `research` (~65 tokens)

Deep web research on a topic. Opens multiple tabs, reads pages, synthesizes findings.

Input parameters:

- `depth` (number): Research depth (1-3). Default: 2
- `tabId` (string): Target tab ID
- `topic` (string, required): Research topic or question

### `tabs` (~29 tokens)

List all open browser tabs with their URLs and titles.

Input parameters:

- `tabId` (string): Target tab ID

### `preview` (~43 tokens)

Pre-fetch a URL without navigating. Returns page description without leaving current page.

Input parameters:

- `tabId` (string): Target tab ID
- `url` (string, required): URL to preview

### `translate` (~65 tokens)

Translate page content or specific text to another language.

Input parameters:

- `tabId` (string): Target tab ID
- `text` (string): Text to translate (omit for full page)
- `to` (string, required): Target language code (e.g., "en", "es", "zh")

### `lens` (~55 tokens)

Visual analysis of the current page via screenshot. Describe what you see or answer questions about the page visually.

Input parameters:

- `question` (string, required): What to analyze or look for in the page
- `tabId` (string): Target tab ID

### `abort` (~50 tokens)

Cancel a pending tool call by callId, or pass callId="all" to cancel everything.

Input parameters:

- `callId` (string, required): The call ID to cancel, or "all" to cancel all pending calls

### `status` (~24 tokens)

List all pending tool calls with their callId, toolName, and elapsed time.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/xidik12-oculo/oculo-mcp#diagnostics

## Score history

- 2026-08-03: 66
- 2026-08-02: 63
- 2026-08-01: 27
- 2026-07-31: 43
- 2026-07-30: 45
- 2026-07-28: 45
- 2026-07-27: 24

## Links

- npm package: https://www.npmjs.com/package/oculo-mcp
- Socket report: https://socket.dev/npm/package/oculo-mcp
- Repository: https://github.com/xidik12/oculo
- Changelog RSS feed: https://verifymcp.io/servers/xidik12-oculo/oculo-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/xidik12-oculo/oculo-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/xidik12-oculo/oculo-mcp