Obscura MCP

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

# Installnpm install -g obscura-mcp
# Verifyobscura-mcp --version
# Start MCP server (stdio — primary transport)obscura-mcp --transport stdio
# Or with HTTP transportobscura-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.

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

Development

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

git clone https://github.com/Metadrama/obscura-mcpcd obscura-mcpnpm installnpm run buildnpm 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