Content
# obscura-mcp — ARCHIVED
> **⚠️ Archived.** Upstream ships native MCP since [v0.1.4](https://github.com/h4ckf0r0day/obscura/releases/tag/v0.1.4) (`obscura mcp`). npm package deprecated.
[](https://www.npmjs.com/package/obscura-mcp)
[](LICENSE)
An MCP server adapter for [Obscura](https://github.com/h4ckf0r0day/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
```bash
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:
```bash
npm install -g obscura-mcp@dev
```
To use a custom binary path:
```bash
export OBSCURA_PATH=/path/to/obscura
```
## Quick Start
```bash
# 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):**
```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"`:
```json
{
"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
```json
{
"mcpServers": {
"obscura-mcp": {
"command": "obscura-mcp",
"args": ["--transport", "stdio"]
}
}
}
```
### VS Code (Cline extension)
```json
{
"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.
```bash
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
