Obscura MCP
MCP server adapter for Obscura Rust headless browser β web scraping with anti-detection.
Ask AI about Obscura MCP
Powered by Claude Β· Grounded in docs
I know everything about Obscura MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
obscura-mcp
An MCP server adapter for Obscura, a lightweight Rust headless browser for scraping and AI agent automation.
Exposes Obscura's native CDP capabilities through a clean MCP interface β no Chrome dependency, no heavyweight browser automation.
Installation
npm install -g obscura-mcp
The npm package itself is a lightweight Node.js wrapper (~20 KB). The browser binary (~80 MB) is downloaded automatically on first use β no separate install step needed.
The binary is cached at ~/.obscura/bin/ and survives npm upgrades.
To use a custom binary path:
export OBSCURA_PATH=/path/to/obscura
Quick Start
# Install
npm install -g obscura-mcp
# Verify
obscura-mcp --version
# Start MCP server (stdio β primary transport)
obscura-mcp --transport stdio
# Or with HTTP transport
obscura-mcp --transport streamable-http
Most MCP clients (Claude Desktop, Cline, Continue) connect via stdio. The streamable-http transport is also supported for custom integrations.
Tools
Four tools cover the essentials of browsing, interacting, and scraping β read pages, click elements, run persistent sessions, and scrape at scale.
browse_page β one-shot page reading
Get content from any page in a single call. Combine output format with optional JavaScript evaluation.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | β | The URL to visit |
format | "text" | "markdown" | "html" | "links" | "cookies" | "axtree" | "layout" | "text" | Output format |
eval | string | β | JavaScript expression to evaluate (appended to output) |
cookies | array | β | Cookies to inject [{name, value, domain?, path?, ...}] |
user_agent | string | β | Override the browser user-agent string |
headers | object | β | Extra HTTP headers {key: value, ...} |
Examples:
browse_page(url: "https://example.com")
browse_page(url: "https://example.com", format: "markdown")
browse_page(url: "https://example.com", format: "axtree")
browse_page(url: "https://example.com", format: "layout")
browse_page(url: "https://example.com", user_agent: "TestBot/1.0")
format | What you get |
|---|---|
"text" | Plain text β stripped of HTML tags, scripts, styles |
"markdown" | Clean markdown β uses Obscura's native LP.getMarkdown CDP |
"html" | Raw HTML markup |
"links" | All href values β one per line |
"cookies" | Cookies with name, value, domain, path, expiry |
"axtree" | Accessibility tree β roles, names, values of all elements |
"layout" | Viewport metrics β dimensions, scroll offsets, device scale |
When eval is provided, the JavaScript result is appended to the format output under a --- eval --- divider.
browse_interact β one-shot page actions
Click an element or type text into a page. One call, no session management needed. For multi-step interactions (login β wait β extract), use browse_session instead.
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string | β | The URL to visit |
action | "click" | "type" | β | Action to perform |
selector | string | β | CSS selector for the target element |
text | string | β | Text to type (required when action is "type") |
cookies | array | β | Cookies to inject [{name, value, ...}] |
Examples:
browse_interact(url: "https://example.com", action: "click", selector: "a")
browse_interact(url: "https://duckduckgo.com", action: "type", selector: "input[name=q]", text: "search query")
Both actions create a fresh page, perform the action, and close. The page context does not persist β for sequential interactions (type into a form, then click submit), use browse_session instead.
browse_session β multi-step persistent sessions
Create a persistent browser session, interact with it across multiple calls, then close. Sessions auto-close after 5 minutes of inactivity. Multiple sessions can run simultaneously.
| Parameter | Type | Required for | Description |
|---|---|---|---|
action | "create" | "close" | "list" | "goto" | "wait" | "extract" | "click" | "type" | All | What to do |
session_id | string | All except create, list | Session ID from create |
url | string | create, goto | URL to navigate to |
selector | string | wait, click, type | CSS selector |
expression | string | wait (if no selector), extract | JavaScript expression |
text | string | type | Text to type |
timeout | number | wait (optional) | Max wait in ms (default 30000, max 120000) |
user_agent | string | create, goto | Override user-agent string for navigation |
headers | object | create, goto | Extra HTTP headers {key: value, ...} |
clear_cookies | boolean | create | Clear all browser cookies on session creation |
Session lifecycle:
action | What it does | Returns |
|---|---|---|
create | Opens a new browser tab. Optionally clears cookies. | Session ID |
close | Releases the tab and all its resources. Idempotent. | Confirmation |
list | Shows all active sessions with timestamps. | Session list |
goto | Navigates to a new URL. Page stays alive. | Confirmation |
wait | Polls until a CSS selector exists or a JS expression returns true. | Confirmation |
extract | Evaluates JavaScript and returns the result. | Eval result |
click | Clicks an element by CSS selector. | Coordinates |
type | Types text into an input field. | Confirmation |
Login flow example:
browse_session(action: "create", url: "https://example.com/login")
β "Created session: session_1"
browse_session(action: "type", session_id: "session_1", selector: "#username", text: "user")
browse_session(action: "type", session_id: "session_1", selector: "#password", text: "pass")
browse_session(action: "click", session_id: "session_1", selector: "#login-btn")
browse_session(action: "wait", session_id: "session_1", selector: ".dashboard", timeout: 10000)
browse_session(action: "extract", session_id: "session_1", expression: "document.title")
browse_session(action: "close", session_id: "session_1")
Multi-article browsing example:
browse_session(action: "create")
browse_session(action: "goto", session_id: "session_1", url: "https://en.wikipedia.org/wiki/JavaScript")
browse_session(action: "extract", session_id: "session_1", expression: "document.title")
browse_session(action: "goto", session_id: "session_1", url: "https://en.wikipedia.org/wiki/Python")
browse_session(action: "extract", session_id: "session_1", expression: "document.title")
browse_session(action: "close", session_id: "session_1")
browse_scrape β parallel bulk scraping
Scrape multiple URLs simultaneously using isolated worker processes. Each URL gets its own headless browser worker β built on top of Obscura's native scrape command with obscura-worker.
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
urls | string[] | β | 1000 | URLs to scrape in parallel |
eval | string | β | β | JavaScript expression to evaluate per page |
concurrency | number | 10 | 100 | Number of parallel worker processes |
timeout | number | 60 | 300 | Per-worker timeout in seconds |
Example:
browse_scrape(urls: ["https://news.ycombinator.com", "https://example.com"], eval: "document.title", concurrency: 25)
Output format (JSON):
{
"total_urls": 2,
"concurrency": 25,
"total_time_ms": 1250,
"avg_time_ms": 625.0,
"results": [
{
"url": "https://news.ycombinator.com",
"title": "Hacker News",
"eval": "Hacker News",
"time_ms": 612,
"worker": 0
},
{
"url": "https://example.com",
"eval": "Example Domain",
"time_ms": 638,
"worker": 1
}
]
}
On errors (timeout, network failure, etc.), the per-URL result includes an "error" field instead of "eval":
{
"url": "https://slow-site.com",
"error": "timeout",
"time_ms": 60000
}
This is the tool that directly leverages Obscura's core advantage over headless Chrome: lightweight parallel scraping with built-in stealth. The ~30 MB per-worker memory footprint means 100 concurrent workers use less memory than a single Chrome instance.
Configuration
Claude Desktop / Cline / Continue / Any MCP client
{
"mcpServers": {
"obscura-mcp": {
"command": "obscura-mcp",
"args": ["--transport", "stdio"]
}
}
}
VS Code (Cline extension)
{
"servers": {
"obscura-mcp": {
"command": "obscura-mcp",
"args": ["--transport", "stdio"]
}
}
}
After global npm install, obscura-mcp is on your PATH β no absolute paths needed.
Environment Variables
| Variable | Default | Description |
|---|---|---|
OBSCURA_PATH | β | Path to custom Obscura binary |
MCP_HTTP_HOST | 127.0.0.1 | HTTP transport host |
MCP_HTTP_PORT | 3000 | HTTP transport port |
MCP_TRANSPORT | stdio | Transport mode: stdio or streamable-http |
OBSCURA_STARTUP_TIMEOUT_MS | 15000 | Milliseconds to wait for Obscura CDP to start |
OBSCURA_NAVIGATION_WAIT_MS | 3000 | Milliseconds to wait after page navigation |
CDP_REQUEST_TIMEOUT_MS | 10000 | Milliseconds to wait for CDP response |
Why Obscura?
- No Chrome β pure Rust, no 200 MB browser bundle
- CDP-native β exposes Chrome DevTools Protocol directly
- Anti-detection β built-in stealth for scraping-resistant sites
- Tiny footprint β ~15 MB binary, starts in milliseconds
License
MIT
