https://github.com/epicsagas/obscura-plugin
MCP server for Obscura headless browser — CLI wrapper for AI agent integration with web scraping, JavaScript rendering, and browser automation
https://github.com/epicsagas/obscura-plugin
ai-agent browser-automation cli headless-browser mcp mcp-server rust web-scraping
Last synced: 4 days ago
JSON representation
MCP server for Obscura headless browser — CLI wrapper for AI agent integration with web scraping, JavaScript rendering, and browser automation
- Host: GitHub
- URL: https://github.com/epicsagas/obscura-plugin
- Owner: epicsagas
- License: apache-2.0
- Created: 2026-05-14T06:07:32.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-05-19T05:51:18.000Z (about 2 months ago)
- Last Synced: 2026-05-19T05:57:45.963Z (about 2 months ago)
- Topics: ai-agent, browser-automation, cli, headless-browser, mcp, mcp-server, rust, web-scraping
- Language: Rust
- Size: 91.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# obscura-plugin
Skill-driven plugin for [Obscura](https://github.com/h4ckf0r0day/obscura) headless browser — gives AI coding agents direct access to web scraping and browser automation via slash commands.
> **Two approaches in Obscura:**
> - `obscura-plugin` (this plugin) — skill-driven with read-only commands (`obscura_fetch`, `obscura_scrape`, etc.), designed for autonomous agent pipelines
## Install
### Claude Code (zero-touch)
`obscura-plugin` ships a `.claude-plugin/` manifest. Register the marketplace source once, then install:
```bash
claude plugin marketplace add epicsagas/plugins
claude plugin install obscura-plugin
```
The `SessionStart` hook downloads `obscura` and `obscura-worker` automatically on first load. No manual steps needed.
### Codex CLI
```bash
codex plugin marketplace add epicsagas/plugins
codex plugin install obscura-plugin
```
Skills and agents are available immediately — no further steps needed.
### Antigravity
```bash
agy plugin install https://github.com/epicsagas/obscura-plugin
```
---
> `obscura-plugin install` automatically downloads the `obscura` and `obscura-worker` binaries from [Obscura releases](https://github.com/h4ckf0r0day/obscura/releases). Linux requires glibc 2.35+ (Ubuntu 22.04+).
### macOS / Linux
```bash
# pre-built binary, no Rust required
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/epicsagas/obscura-plugin/releases/latest/download/obscura-plugin-installer.sh | sh
```
### Windows
```powershell
# pre-built binary, no Rust required
irm https://github.com/epicsagas/obscura-plugin/releases/latest/download/obscura-plugin-installer.ps1 | iex
```
### Homebrew (macOS / Linux)
```bash
brew install epicsagas/tap/obscura-plugin
```
### Via Rust toolchain
```bash
# pre-built binary via Rust toolchain (fast)
cargo binstall obscura-plugin
# build from source (requires Rust toolchain)
cargo install obscura-plugin
```
> `obscura-plugin --version` to verify. Update with `brew upgrade obscura-plugin` or re-run the installer script.
### Register with your AI tools
After installing the binary, run `obscura-plugin install` to connect it to your tools:
```bash
obscura-plugin install # interactive — pick which tools
obscura-plugin install cursor # Cursor
obscura-plugin install opencode # OpenCode
obscura-plugin install cline # Cline
obscura-plugin install all # all at once
```
```bash
obscura-plugin uninstall cursor # remove from a specific tool
obscura-plugin list # show supported tools and status
```
### What gets installed
| Tool | Skills | Method |
|------|--------|--------|
| Claude Code | plugin auto-discovers | `.claude-plugin/` manifest |
| Codex CLI | plugin auto-discovers | `.codex-plugin/` manifest |
| Antigravity | plugin auto-discovers | root `plugin.json` |
| Cursor | `~/.cursor/rules/` | `obscura-plugin install` |
| OpenCode | `~/.opencode/skills/` | `obscura-plugin install` |
| Cline | `~/.cline/skills/` | `obscura-plugin install` |
## Skills
Registered skills are available as slash commands inside your agent:
```
/obscura-fetch [--dump html|text|links|markdown] [--eval ] [--selector ] [--stealth]
/obscura-scrape ... [--eval ] [--concurrency ] [--format json|text]
/obscura-pipeline # discover links → scrape in one pipeline
/obscura-crawl # recursive crawl with depth control, pagination, sitemap discovery
```
### Skill parameters
**`obscura-fetch`**
| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | URL to fetch *(required)* |
| `dump` | string | `html` · `text` · `links` · `markdown` (default: `html`) |
| `eval` | string | JavaScript expression to evaluate |
| `wait_until` | string | `load` · `domcontentloaded` · `networkidle0` (default: `load`) |
| `selector` | string | CSS selector to wait for before returning |
| `stealth` | boolean | Enable anti-detection + tracker blocking¹ |
| `user_agent` | string | Custom User-Agent string |
| `quiet` | boolean | Suppress banner (default: `true`) |
**`obscura-scrape`**
| Parameter | Type | Description |
|-----------|------|-------------|
| `urls` | string[] | URLs to scrape *(required)* |
| `eval` | string | JavaScript expression applied to each page |
| `concurrency` | number | Parallel workers (default: `10`) |
| `format` | string | `json` · `text` (default: `json`) |
| `proxy` | string | HTTP/SOCKS5 proxy URL for all workers |
**`obscura-pipeline`**
| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | Index page URL *(required)* |
| `selector` | string | CSS selector for link extraction |
| `concurrency` | number | Parallel workers for scraping |
| `stealth` | boolean | Anti-detection mode¹ |
> ¹ **Stealth mode** requires Obscura built with `--features stealth`. The default release binary includes stealth.
**`obscura-crawl`**
| Parameter | Type | Description |
|-----------|------|-------------|
| `url` | string | Seed URL to start crawling from *(required)* |
| `max_depth` | number | Maximum crawl depth (default: `3`) |
| `same_domain` | boolean | Only follow links on the same domain (default: `true`) |
| `url_filter` | string | Regex/glob pattern to filter URLs by path |
## The `obscura-browser` agent
A self-directed web data collection specialist. Invoke it for tasks like:
> "Collect all product titles and prices from these 30 URLs"
> "Fetch the docs at example.com/api and summarize the endpoints"
> "Scrape the HN front page and return structured JSON"
> "Crawl example.com/blog up to depth 2 and extract all post titles"
The agent knows Obscura's limits — it stops and escalates to Playwright when login or interaction is required. Supports agentic crawling with depth control, pagination detection, sitemap discovery, and adaptive extraction.
## Project structure
```
obscura-plugin/
skills/ # shared skills
obscura-fetch/SKILL.md
obscura-scrape/SKILL.md
obscura-pipeline/SKILL.md
obscura-crawl/SKILL.md
agents/ # shared agent (markdown)
obscura-browser.md
scripts/
install.js # binary bootstrap (SessionStart hook)
.claude-plugin/ # Claude Code plugin
plugin.json, hooks.json, marketplace.json
.codex-plugin/ # Codex CLI plugin
plugin.json, hooks.json
agents/obscura-browser.toml # Codex-specific TOML agent
plugin.json # Antigravity (agy) plugin marker
hooks.json # Antigravity hooks
src/ # Rust installer (cursor, opencode, cline)
tests/
Cargo.toml
```
## Build from source
```bash
cargo build --release
./target/release/obscura-plugin --help
```
## License
Apache 2.0