obscura-mcp

MCP server that uses Obscura as the browser engine and Playwright as the CDP client.

Architecture

AI Agent (Claude, etc.)
    │  MCP protocol (stdio)
    ▼
obscura-mcp (Node.js)
    │  Playwright-core connectOverCDP()
    ▼
Obscura (Rust CDP server, ws://127.0.0.1:9222)
    │  V8 JavaScript engine
    ▼
Web Pages

Why Obscura over headless Chrome?

| | Obscura | Headless Chrome | |---|---|---| | Memory | 30 MB | 200+ MB | | Page load | ~85 ms | ~500 ms | | Startup | Instant | ~2 s | | Anti-detect | Built-in | ❌ | | Playwright compat | ✅ | ✅ |

Setup

1. Install Obscura

# Linux x86_64
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
chmod +x obscura

2. Install this MCP server

npm install

3. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obscura-browser": {
      "command": "node",
      "args": ["/path/to/obscura-mcp/index.mjs"],
      "env": {
        "OBSCURA_PATH": "/path/to/obscura",
        "OBSCURA_PORT": "9222",
        "OBSCURA_STEALTH": "true"
      }
    }
  }
}

4. (Optional) Use an already-running Obscura server

# Terminal 1: start Obscura manually
./obscura serve --port 9222 --stealth

# Terminal 2: start MCP server pointing to it
OBSCURA_EXTERNAL=true node index.mjs

Environment Variables

| Variable | Default | Description | |---|---|---| | OBSCURA_PATH | ./obscura | Path to Obscura binary | | OBSCURA_PORT | 9222 | CDP WebSocket port | | OBSCURA_STEALTH | true | Enable anti-detection | | OBSCURA_EXTERNAL | false | Don't manage Obscura process | | CONNECT_TIMEOUT | 10000 | CDP connect timeout (ms) | | NAV_TIMEOUT | 30000 | Navigation timeout (ms) |

Available Tools

| Tool | Description | |---|---| | browser_navigate | Navigate to a URL | | browser_screenshot | Capture a screenshot | | browser_get_content | Get page as HTML / text / markdown | | browser_evaluate | Run JavaScript on the page | | browser_click | Click an element by CSS selector | | browser_fill | Type into an input field | | browser_scrape_parallel | Scrape multiple URLs concurrently | | browser_get_cookies | Get all cookies | | browser_set_cookies | Inject cookies | | browser_close | Shut down browser + Obscura |

Example Usage (via AI agent)

# Navigate and extract data
browser_navigate { url: "https://news.ycombinator.com" }
browser_evaluate { expression: "Array.from(document.querySelectorAll('.titleline > a')).map(a => a.textContent)" }

# Parallel scraping (Obscura advantage)
browser_scrape_parallel {
  urls: ["https://site1.com", "https://site2.com", "https://site3.com"],
  expression: "document.title",
  concurrency: 10
}

# Stealth form submission
browser_navigate { url: "https://example.com/login" }
browser_fill { selector: "#email", value: "user@example.com" }
browser_fill { selector: "#password", value: "secret" }
browser_click { selector: "button[type=submit]" }

MCP Servers