obscura-mcp — ARCHIVED

⚠️ Archived. Upstream ships native MCP since v0.1.4 (obscura mcp). npm package deprecated.

npm version License: MIT

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 small 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.

Pre-release builds are published under the dev tag:

npm install -g obscura-mcp@dev

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 browsing, interacting, session persistence, and bulk scraping.

`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, ...}`
`stealth`	`boolean`	`true`	Accepted for compatibility; stealth is controlled by the Obscura server

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. 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, ...}]`
`stealth`	`boolean`	`true`	Accepted for compatibility; stealth is controlled by the Obscura server

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
`OBSCURA_STEALTH`	—	Enable stealth mode (anti-detection)
`OBSCURA_PROXY`	—	Proxy URL for all traffic
`OBSCURA_USER_AGENT`	—	Default user-agent override
`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

Development

Built with TypeScript, compiled to dist/, tested with Vitest.

git clone https://github.com/Metadrama/obscura-mcp
cd obscura-mcp
npm install
npm run build
npm test

All 36 integration tests run against a real Obscura binary (auto-downloaded on first run). Tests use StdioClientTransport and cover every tool, format, and action.

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

obscura-mcp

obscura-mcp — ARCHIVED

Installation

Quick Start

Tools

`browse_page` — one-shot page reading

`browse_interact` — one-shot page actions

`browse_session` — multi-step persistent sessions

`browse_scrape` — parallel bulk scraping

Configuration

Claude Desktop / Cline / Continue / Any MCP client

VS Code (Cline extension)

Environment Variables

Development

Why Obscura?

License

Resources

Tools

Latest Blog Posts

MCP directory API

obscura-mcp — ARCHIVED

Installation

Quick Start

Tools

browse_page — one-shot page reading

browse_interact — one-shot page actions

browse_session — multi-step persistent sessions

browse_scrape — parallel bulk scraping

Configuration

Claude Desktop / Cline / Continue / Any MCP client

VS Code (Cline extension)

Environment Variables

Development

Why Obscura?

License

Resources

Tools

Latest Blog Posts

MCP directory API

`browse_page` — one-shot page reading

`browse_interact` — one-shot page actions

`browse_session` — multi-step persistent sessions

`browse_scrape` — parallel bulk scraping