Oculo MCP server
✓ VerifiedAn AI-powered Chromium browser that allows MCP clients to see and drive web pages through compact, tool-based automation.
Also known as xidik12/oculo, oculo-mcp
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.4.1
- Last commit
- Jul 20, 2026
- License
- MIT
What is Oculo MCP?
Oculo is an AI-powered Chromium browser that allows MCP clients to see and drive web pages through compact, tool-based automation.
Summary generated from the project's README
About Oculo MCP server
Developers using Claude Code, Cursor, or Windsurf can grant their AI agents the ability to interact with the live web through Oculo. This tool provides a full Chromium engine that functions as a native desktop browser rather than a simple scraper or extension. It allows agents to perform complex tasks like reading the DOM, filling forms, and managing multi-step automation pipelines using 12 specialized MCP tools.
To use it, you connect your MCP client to the oculo-mcp bridge, which communicates with the running Electron application. The system is designed for efficiency, returning compact text responses that typically use under 300 tokens per flow. Security is integrated through an OS keychain vault for credentials and a redaction system that strips sensitive data like credit card numbers or API keys from responses. It also includes a permission gate with four levels to control how much autonomy the agent has over actions like clicking or deleting accounts.
What you can do with it
- 1Automated web loginsAn agent can log into a website and perform actions like starring a repository without the model ever seeing the actual password.
- 2Structured data extractionYou can instruct an AI to find and pull specific information from search results, tables, or articles.
- 3Complex form completionA developer can have an agent navigate to a contact page and fill out all necessary fields automatically.
- 4Deep web researchThe research tool allows an agent to open multiple tabs and synthesize findings from various web pages.
Written from the project's README. Every use case is checked against a quote from it.
How to install Oculo MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Oculo MCP in Claude Code
$ claude mcp add oculo -- npx -y oculo-mcpInstall Oculo MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"oculo": {
"command": "npx",
"args": [
"-y",
"oculo-mcp"
]
}
}
}Install Oculo MCP in VS Code
.vscode/mcp.json
{
"servers": {
"oculo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"oculo-mcp"
]
}
}
}Install Oculo MCP in VS Code CLI
$ code --add-mcp '{"name":"oculo","type":"stdio","command":"npx","args":["-y","oculo-mcp"]}'Install Oculo MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"oculo": {
"command": "npx",
"args": [
"-y",
"oculo-mcp"
]
}
}
}Install Oculo MCP in Codex
$ codex mcp add oculo -- npx -y oculo-mcpInstall Oculo MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.oculo] command = "npx" args = ["-y", "oculo-mcp"]
Install Oculo MCP in Gemini CLI
$ gemini mcp add -s user oculo npx -- -y oculo-mcpInstall Oculo MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"oculo": {
"command": "npx",
"args": [
"-y",
"oculo-mcp"
]
}
}
}Configuration
OCULO_HEADLESS
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablexidik12/oculo is public and reachablegithub.com/xidik12/oculo ↗Pass
- Package names this repository as its sourceoculo-mcp names xidik12/oculo as sourcenpmjs.com/package/oculo-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-07-20github.com/xidik12/oculo ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from oculo-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubOculo 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:
| Capability | |
|---|---|
| Native browser | Full Chromium engine — not a wrapper, extension, or headless scraper |
| 12 MCP tools | page, act, fill, read, run, media, shell, tabs, research, preview, translate, lens |
| < 300 tokens / flow | Compact text responses by default — cheaper than screenshot-based approaches |
| Self-healing automation | Selector caching + DOM diffing — 44%+ faster on repeated workflows |
| Multi-provider AI | Built-in chat with Claude, OpenAI, Gemini, Grok, OpenClaw, Ollama |
| 4-level security | auto / notify / confirm / blocked permission gate on every action |
| OS keychain vault | Credentials encrypted via electron.safeStorage (macOS Keychain / Windows DPAPI) |
| PII redaction | Credit cards, SSNs, JWTs, API keys, Bearer tokens stripped from every MCP response |
| Anti-injection | Content boundary markers + regex-based prompt-injection detection |
| 19 stealth patches | Navigator, WebGL, canvas, WebRTC, audio, font, battery, and screen fingerprint defenses |
| Headless mode | Run without a window — Docker support included |
| Cross-platform | macOS, Windows, Linux |
| Python SDK | pip install oculo — sync and async clients |
Each tool does one thing and returns the smallest useful answer. Token cost is the response size the agent pays for.
| Tool | What it does | Token cost |
|---|---|---|
page |
Describe the current page — headings, forms, buttons, links. Compact, a11y (ref-tagged), and markdown modes | ~30–80 |
act |
Navigate, click, hover, scroll, type, press keys, login via vault, manage tabs, cookies, proxy, recording | ~1 line |
fill |
Fill form fields by label/placeholder matching, optional submit. Text, select, checkbox, contenteditable | ~1 line |
read |
Extract structured data — search results, tables, lists, articles | compact |
run |
Multi-step pipeline with conditionals (page/act/fill/read/wait/if). Cached for replay |
header + last |
media |
Generate images (Nano Banana 2 / DALL·E 3) or video (Veo 3.1); image-to-image editing | file path |
shell |
Execute shell commands non-interactively (ls, npm, git, python, …) | stdout + stderr |
tabs |
List all open browser tabs with URLs and titles | compact |
research |
Deep web research — opens multiple tabs, reads pages, synthesizes findings | synthesized |
preview |
Pre-fetch a URL without navigating away from the current page | page description |
translate |
Translate page content or specific text to any language | translated text |
lens |
Visual analysis of the current page via screenshot + AI vision | description |
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
| Level | Actions | Behavior |
|---|---|---|
| Auto | navigate, page, read, scroll, screenshot, back, forward, reload, hover, listTabs, switchTab, preview, translate, lens | Executes silently |
| Notify | click, type, fill, select, press, submit, newTab, closeTab | Executes + OS notification |
| Confirm | payment, delete_account, change_password, send_email, download, oauth, shell, evaluate, setProxy, startRecording | Native dialog approval required |
| Blocked | read_vault, export_cookies, export_tokens, disable_security | Always rejected |
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
- Every MCP response passes through a redactor that strips credit-card numbers, SSNs, JWTs, API keys, private keys, and Bearer tokens.
- Page content handed to the model is wrapped in boundary markers, and regex-based detection blocks prompt-injection attempts embedded in that content.
Stealth (19 patches)
Navigator (webdriver, languages, plugins, mimeTypes, connection, hardwareConcurrency, deviceMemory), window (chrome API, dimensions), WebGL (vendor/renderer spoofing), canvas (per-call fingerprint randomization), WebRTC (IP-leak prevention), AudioContext, font enumeration blocking, Battery API, and screen-resolution randomization.
Self-healing automation
After a successful act/fill, selectors are cached with stability scores — id and data-testid = 10, aria-label = 9, role+name = 8, text = 7, css = 5. On the next run, DOM diffing picks the strategy:
- > 80% similarity — replay from cache, no LLM call.
- 50–80% — fall back to alternative selectors.
- < 50% — re-engage the AI for a fresh resolution.
That's where the 44%+ speed-up on repeated workflows comes from.
Built-in AI chat
Oculo also ships a side-panel chat that talks to multiple providers directly:
| Provider | Auth | Models |
|---|---|---|
| Claude | API key or CLI subscription | Opus, Sonnet, Haiku |
| OpenAI | API key or Codex CLI | GPT-4o, GPT-4o mini, o1, o3 |
| Gemini | API key | 2.0 Flash, 1.5 Pro, 1.5 Flash |
| Grok | API key | Grok 2, Grok 2 Mini |
| Ollama | Local (no key) | Any pulled model |
| OpenClaw | API key | OpenClaw models |
Building from source
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
Prerequisites: Node.js 20+, npm (not pnpm/yarn — native modules require 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
Contributing
See CONTRIBUTING.md for development setup, architecture details, and how to add a new MCP tool.
Donate
If Oculo saves you time, you can support development — BTC: 12yRGpUfFznzZoz4yVfZKRxLSkAwbanw2B
License
MIT © 2026 Salakhitdinov Khidayotullo
Oculo MCP questions
How do I add Oculo MCP to Claude Code?
Run claude mcp add oculo -- npx -y oculo-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Oculo MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can Oculo do with an AI agent?
It allows agents to read the DOM, click, fill forms, extract data, and run multi-step pipelines using 12 compact tools.
Does Oculo protect against prompt injection?
Yes, it uses content boundary markers and regex-based detection to block prompt-injection attempts.