oculo

ウェブサイト · ダウンロード · クイックスタート · MCP ツール · アーキテクチャ · コントリビューション

Oculo は、Model Context Protocol に対応したフル Chromium デスクトップブラウザーです。Claude Code、Cursor、Windsurf、またはあらゆる MCP クライアントを接続すれば、エージェントが実際のウェブページを見て、操作できます。12 個のコンパクトなツールを通じて、DOM の読み取り、クリック、フォーム入力、データ抽出、複数ステップのパイプライン実行を行い、1 つのフローにつき 300 トークン未満で応答します。

Cursor : VSCode :: Oculo : Chrome

動作を見る

エージェントが意図を伝えると、Oculo はそれを少数の小さなツール呼び出しに変換し、簡潔で機密情報を除去した結果を返します。数メガバイトのスクリーンショットを返すことはありません。

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 エンジンをローカルマシンで実行し、その上にエージェントを優先した制御レイヤーを追加します。この組み合わせが Oculo の特長です。

各ツールは 1 つの処理を行い、必要最小限の結果を返します。エージェントが支払うトークンコストは、応答のサイズです。

ボーナス： webmcp_list と webmcp_call を使うと、WebMCP プロトコル経由でページが宣言したツールを検出して呼び出せます。

stdio ではなく HTTP を使う理由　Electron の <webview> にアクセスできるのはレンダラープロセスだけです。stdio が動作するメインプロセスからは、ページのコンテンツにアクセスできません。HTTP ブリッジは、メインプロセスからレンダラーへの IPC を介してこの境界を越えます。

ポートの検出。 起動時に Oculo は port:authtoken を ~/.oculo-port に書き込みます。bin/oculo-mcp.mjs ブリッジがこれを自動的に読み込むため、アプリを閉じていてもツール定義を検出できます。ただし、実行には Oculo の起動が必要です。

1. インストール

リリースから最新ビルドをダウンロードするか、ソースから実行します。

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、dimensions）、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（ネイティブモジュールに npm が必要なため、pnpm／yarn は不可）、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