How do I install Obscura MCP?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Obscura MCP need an API key?

No required environment variable is listed on this record.

What transport does Obscura MCP use?

Obscura MCP runs locally over stdio.

When was Obscura MCP last checked?

Last checked 2026-11-09. MCP server adapter for Obscura Rust headless browser — web scraping with anti-detection.

Obscura MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y [email protected]

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.metadrama-obscura-mcp -- npx -y obscura-mcp@0.1.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.metadrama-obscura-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "[email protected]"8      ]9    }10  }11}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.1.1
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

obscura-mcp — ARCHIVED

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

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

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Obscura MCP?

Does Obscura MCP need an API key?

What transport does Obscura MCP use?

When was Obscura MCP last checked?

Documentation

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

`browse_page` — one-shot page reading

`browse_interact` — one-shot page actions

`browse_session` — multi-step persistent sessions

`browse_scrape` — parallel bulk scraping