oculo

官方网站 · 下载 · 快速开始 · MCP 工具 · 架构 · 参与贡献

Oculo 是一款完整的 Chromium 桌面浏览器，支持 Model Context Protocol。让 Claude Code、Cursor、Windsurf 或任何 MCP 客户端连接到它，你的 Agent 就能看见并操控真实网页——读取 DOM、点击、填写表单、提取数据、运行多步流水线——通过 12 个精简工具完成，每个工作流的响应都不到 300 个 token。

Cursor : VSCode :: Oculo : Chrome

实际效果

你的 Agent 描述意图；Oculo 将其转化为几次简短的工具调用，并返回精炼且经过脱敏的结果——而非数 MB 的屏幕截图。

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 在你的机器上运行真正的 Chromium 引擎，并在其上添加以 Agent 为先的控制层。这种组合正是它的价值所在：

每个工具只做一件事，并返回最精简且实用的答案。token 成本就是 Agent 为响应大小付出的代价。

额外工具： webmcp_list 和 webmcp_call 可通过 WebMCP 协议发现并调用页面声明的工具。

为什么使用 HTTP 而不是 stdio？ Electron 的 <webview> 只能从渲染进程访问。主进程（stdio 所在进程）无法访问页面内容。HTTP 桥接通过主进程到渲染进程的 IPC 跨越这一边界。

端口发现。 Oculo 启动时会将 port:authtoken 写入 ~/.oculo-port。bin/oculo-mcp.mjs 桥接程序会自动读取该文件，因此即使应用已关闭，工具定义仍可被发现 — 只有执行工具时才需要 Oculo 正在运行。

1. 安装

从 Releases 获取最新版本，或从源码运行：

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

2. 在 MCP 客户端中注册

Claude Code

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

Cursor / Windsurf — 将以下内容添加到 MCP 配置（.cursor/mcp.json 或同类文件）：

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

3. （可选）无头模式和 Docker

在没有可见窗口的情况下运行，适用于 CI/CD、抓取或服务端自动化：

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. （可选）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": "[email protected]", "Message": "Hello!"}, submit=True)
results = client.read("search results", format="json")

另有一个异步 AsyncOculoClient，接口相同。

每项操作都会经过权限门控，每个响应在送达模型之前都会经过脱敏。

权限级别

凭据保险库

• 使用 electron.safeStorage 加密 → OS Keychain（macOS）/ DPAPI（Windows）。
• 密码绝不会通过 IPC 或 MCP 返回——只会公开域名和用户名。
• act({action: "login", site: "github.com"}) 会检索并填写凭据，全程不会让模型看到这些凭据。

脱敏与反注入

• 每个 MCP 响应都会经过脱敏器，移除信用卡号、SSN、JWT、API 密钥、私钥和 Bearer 令牌。
• 提供给模型的页面内容会用边界标记包裹，基于正则表达式的检测机制会阻止嵌入在内容中的提示词注入尝试。

隐身（19 项补丁）

Navigator（webdriver、languages、plugins、mimeTypes、connection、hardwareConcurrency、deviceMemory）、window（chrome API、尺寸）、WebGL（伪装 vendor/renderer）、canvas（每次调用时随机化指纹）、WebRTC（防止 IP 泄露）、AudioContext、阻止枚举字体、Battery API，以及随机化屏幕分辨率。

自动修复

成功执行 act/fill 后，会缓存选择器及其稳定性评分——id 和 data-testid = 10，aria-label = 9，role+name = 8，text = 7，css = 5。下次运行时，通过 DOM 差异对比选择策略：

• 相似度 > 80% — 从缓存重放，无需调用 LLM。
• 50–80% — 回退到备用选择器。
• < 50% — 重新调用 AI 进行解析。

重复工作流的速度提升超过 44% 正是由此而来。

内置 AI 聊天

Oculo 还内置了侧边栏聊天功能，可直接与多个提供商对话：

从源代码构建

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

先决条件： Node.js 20+、npm（不使用 pnpm/yarn——原生模块需要 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

贡献

有关开发环境设置、架构详情以及如何添加新的 MCP 工具，请参阅 CONTRIBUTING.md。

捐赠

如果 Oculo 为你节省了时间，你可以支持项目开发——BTC： 12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B

许可证

MIT © 2026 Salakhitdinov Khidayotullo

由 Salakhitdinov Khidayotullo 开发 · getoculo.com