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.

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")

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.

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.

Session lifecycle:

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.

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

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