oculo — Claude Code MCP server: a browser your agent drives
A full Chromium desktop browser that speaks MCP. Useful when your agent needs to click through live pages instead of parsing screenshots.
claude mcp add oculo -- npx -y oculo-mcpWhat oculo does
Oculo is a desktop browser built on Chromium with a control layer for agents. Point Claude, Cursor, Windsurf or another MCP client at it, and the agent can read the DOM, click, fill forms and pull data off real pages. Responses come back as short text rather than megabytes of screenshots.
Twelve tools cover the work. page describes what is on screen, act handles navigation and clicks, fill matches fields by label or placeholder, read extracts tables and lists, run chains steps with conditionals. There is also media for image and video generation, shell for commands, and research for opening several tabs at once. Credentials sit in the OS keychain via electron.safeStorage, so a password never leaves it.
Oculo has to be running for any tool to execute. On startup it publishes the port and auth token to ~/.oculo-port, and the oculo-mcp bridge reaches it over HTTP on port 19516. The reason is Electron's <webview>: only the renderer process can touch page content, and stdio lives in the main process.
What it helps with
- log into a site and perform an action as the user
- fill out and submit a contact form
- scrape a table or list of results from a page
- run a multi-step flow across several tabs
- translate page content into another language
Example prompts for the agent
- Log into github.com and star the xidik12/oculo repo
- Fill out the form at example.com/contact and submit it
- Collect every heading and link from the open page
How to install oculo
Platform CLI
claude mcp add oculo -- npx -y oculo-mcpPlatform CLI
codex mcp add oculo -- npx -y oculo-mcpConfig file
{
"mcpServers": {
"oculo": {
"command": "npx",
"args": [
"-y",
"oculo-mcp"
]
}
}
}Config file
{
"servers": {
"oculo": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"oculo-mcp"
]
}
}
}Platform CLI
gemini mcp add oculo npx -y oculo-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about oculo
How do I install oculo in Claude Code?
Run claude mcp add oculo -- npx -y oculo-mcp. Then start the Oculo browser itself — tools stay silent without it.
What does oculo do?
It gives an agent control of a real Chromium window: navigation, clicks, form filling, data extraction, multi-step pipelines. All through 12 compact MCP tools.
Where do passwords go when logging in?
Into the OS keychain through electron.safeStorage — macOS Keychain or Windows DPAPI. The password is not returned in tool responses.
