The headless browser for AI agents and web scraping
obscura mcp exposes obscura as a Model Context Protocol server so MCP-capable clients (Claude Desktop, Claude Code, etc.) can drive it.
Render-enabled builds can load additional fonts for screenshots and PDF output:
obscura mcp --font-dir /path/to/fonts
Repeat --font-dir to load multiple directories. It recursively loads TTF, TTC,
OTF, and OTC files once before rendering, using the same opt-in font database as
obscura serve. System fonts are not scanned automatically. Invalid directories
fail at startup, and no-render builds reject a nonempty font directory option.
The option works with both stdio and HTTP transports.
Run
Stdio (default, for direct client integration):
obscura mcp
HTTP (for remote or shared use):
obscura mcp --http --port 3000
The HTTP transport binds 127.0.0.1 by default. Bind all interfaces with --host for a container or sidecar deployment:
OBSCURA_MCP_TOKEN="$(openssl rand -hex 32)" \
obscura mcp --http --host 0.0.0.0 --port 3000
With stealth and proxy:
obscura mcp --stealth --proxy http://proxy.example.com:8080
Security
The HTTP transport exposes a privileged browser session. Its guards are:
- Bearer authentication. Set
OBSCURA_MCP_TOKENand send it in theAuthorization: Bearer ...header. A non-loopback bind is refused without a token of at least 32 bytes. - Origin allowlist. Browser requests are refused by default. Set
OBSCURA_MCP_ALLOWED_ORIGINSto permit specific browser origins. Native clients send noOriginand are unaffected. - Resource bounds. Request bodies, headers, JSON-RPC batches, pending work, and live connections are bounded.
OBSCURA_MCP_TOKEN="$(openssl rand -hex 32)" \
OBSCURA_MCP_ALLOWED_ORIGINS="https://app.example.com" \
obscura mcp --http --host 0.0.0.0
Tools exposed
The server keeps a live browser session, so tools operate on the current page rather than taking a URL each call. Navigate first, then read or act.
The active page continues running timers and network callbacks between tool calls over both stdio and HTTP. Task driving is wake-driven and parks when the page is idle; a future timer does not block incoming MCP requests.
Navigation and lifecycle:
browser_navigate,browser_back,browser_forward,browser_reload,browser_close
Read the page:
browser_snapshot: current URL, title, actionable element references, control states, and visible body text. References can be passed directly to interaction tools without a separate listing call. Names use the same native accessibility logic as CDP, including associated labels and ARIA name precedence.max_charsdefaults to 4000 and is shared by whole control descriptions first, then body text. Omission markers are added outside that budget. URL and title are separately capped at 256 characters each;max_chars: 0returns only that metadata. Descriptions preview at most 80 characters per name or value and do not include password control values.browser_markdown,browser_links,browser_extract: page as markdown, link list, or structured content.browser_interactive_elements,browser_detect_forms: actionable elements and form fields.
Snapshots and interactive-element listings exclude HTML/ARIA-hidden content; render builds also apply computed CSS visibility. Hidden text explicitly referenced by a visible control can still supply its accessible name. These are compact browsing context, not a claim of complete accessibility conformance.
browser_get_attribute,browser_count,browser_search: read an attribute, count matches, find text.
Interact:
browser_click,browser_fill,browser_fill_form,browser_type,browser_press_key,browser_select_option,browser_scroll
Wait and run JS:
browser_wait_for,browser_wait_for_text,browser_wait_for_function,browser_evaluate
browser_wait_for_function polls the JavaScript expression in function until
it becomes truthy. timeout defaults to 30000 ms and pollIntervalMs to 100 ms.
browser_evaluate accepts JavaScript scripts, executes them once, and waits for
returned promises. timeoutMs defaults to 5000 ms and bounds synchronous
execution as well as promise settlement. Exceptions, rejected promises, and
timeouts return MCP tool errors (isError: true); a successful JavaScript
null or undefined result is still returned as null text.
Interaction tools also report execution failures as tool errors.
Internal interaction and extraction scripts have a five-second execution and
serialization deadline.
browser_fill_form does not submit if any field fails, and completes a queued
submit navigation before replying. A failed interaction can have partial side
effects; take a fresh snapshot before deciding whether to retry.
Diagnostics:
browser_network_requests,browser_console_messages
Visual output (render-enabled builds):
browser_screenshot: current viewport as an MCPimage/pngcontent block.browser_pdf: current page as an embeddedapplication/pdfresource.
browser_screenshot accepts optional positive width and height values in
CSS pixels and enforces a bounded capture size. browser_pdf accepts
landscape, print_background, scale, paper width/height, and top, bottom,
left, and right margins. Paper dimensions and margins are measured in inches.
Cookies and storage:
browser_get_cookies,browser_set_cookie,browser_clear_cookies,browser_storage_state,browser_set_storage_state
Storage-state export includes localStorage for all stored origins and
sessionStorage for all stored origins in the active tab. Restoration merges
the supplied keys into their declared origins and can run before navigation.
Restored sessionStorage belongs only to the active tab, creating a default
tab if needed; localStorage and cookies belong to the browser context.
Origins must be canonical HTTP(S) origins, and storage entries are [key, value]
string pairs. Invalid input is rejected before mutation. A quota failure returns
a tool error and reports that preceding writes may already have been applied.
Cookie entries pass through the browser's existing cookie validation.
Tabs:
browser_tab_new,browser_tab_list,browser_tab_switch,browser_tab_close
Switching tabs retains JavaScript globals, event listeners, frame state and pending promises. Each open tab keeps its runtime in memory until closed. Autonomous task progress currently belongs to the active tab; retaining a tab does not promise that background work runs while another tab is active.
Element references describe the current rendered page state and can become stale after navigation, interaction, scrolling, or a framework rerender. Take a fresh snapshot or interactive-element listing before acting again.
Treat references as opaque tokens. Each new snapshot or interactive-element listing invalidates the previous tokens. A reference targets the original native element, not a replacement or clone that copies its attributes; stale references return a tool error instead of acting on a different element.
MCP exposes still-image and PDF output. It does not stream video frames; use
CDP Page.startScreencast for activity-driven screencasting.
Web search (optional)
The browser tools act on pages the agent already has a URL for. To let it find
pages first, set OBSCURA_WEB_SEARCH=keenable in the server's environment.
This adds a web_search tool (query, optional limit, default 5, max 50)
that returns one JSON object per line with title, url, and snippet.
Responses larger than 1 MiB after decompression return a tool error.
The tool is not listed unless the variable is set. Each call sends the query
to the Keenable search API (api.keenable.ai) through the configured proxy.
No account is needed. The public endpoint is rate limited per IP; set
KEENABLE_API_KEY to raise the limit.
{
"mcpServers": {
"obscura": {
"command": "/path/to/obscura",
"args": ["mcp"],
"env": { "OBSCURA_WEB_SEARCH": "keenable" }
}
}
}
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"obscura": {
"command": "/path/to/obscura",
"args": ["mcp"]
}
}
}
Restart Claude Desktop. The obscura tools appear in the tool list.
Claude Code
claude mcp add obscura /path/to/obscura mcp
With stealth in config
{
"mcpServers": {
"obscura": {
"command": "/path/to/obscura",
"args": ["mcp", "--stealth"]
}
}
}
Local and private network addresses are blocked by default. CLI and stdio MCP
navigation errors explain the existing --allow-private-network /
OBSCURA_ALLOW_PRIVATE_NETWORK=1 opt-in for your own local services. The hint
does not grant access, is omitted for known metadata endpoints and special
address ranges, and is not shown by the HTTP MCP transport.