Obscura MCP

obscura-mcp — アーカイブ済み

⚠️ アーカイブ済み。 上流では v0.1.4 以降、ネイティブの MCP（obscura mcp）が提供されています。npm パッケージは非推奨です。

スクレイピングや AI エージェントによる自動化に使える軽量な Rust 製ヘッドレスブラウザー、Obscura の MCP サーバーアダプターです。

Obscura のネイティブ CDP 機能を、使いやすい MCP インターフェースを通じて公開します。Chrome への依存や、重量級のブラウザー自動化ツールは不要です。

インストール

npm install -g obscura-mcp

npm パッケージ自体は小さな Node.js ラッパー（約 20 KB）です。ブラウザーバイナリ（約 80 MB）は初回使用時に自動ダウンロードされるため、別途インストールする必要はありません。

バイナリは ~/.obscura/bin/ にキャッシュされ、npm をアップグレードしても保持されます。

プレリリースビルドは dev タグで公開されています。

npm install -g obscura-mcp@dev

カスタムのバイナリパスを指定するには、次のようにします。

export OBSCURA_PATH=/path/to/obscura

クイックスタート

# 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

ほとんどの MCP クライアント（Claude Desktop、Cline、Continue）は stdio で接続します。カスタム統合向けに streamable-http トランスポートもサポートされています。

ツール

ブラウジング、操作、セッションの永続化、一括スクレイピングを、4 つのツールで行えます。

browse_page — 1 回の呼び出しでページを読み取る

1 回の呼び出しで、任意のページのコンテンツを取得します。出力形式と、必要に応じて JavaScript の評価を組み合わせられます。

パラメーター	型	デフォルト	説明
url	string	—	アクセスする URL
format	"text" | "markdown" | "html" | "links" | "cookies" | "axtree" | "layout"	"text"	出力形式
eval	string	—	評価する JavaScript 式（出力に追加されます）
cookies	array	—	注入する Cookie [{name, value, domain?, path?, ...}]
user_agent	string	—	ブラウザーのユーザーエージェント文字列を上書きします
headers	object	—	追加の HTTP ヘッダー {key: value, ...}
stealth	boolean	true	互換性のために受け付けます。ステルス機能は Obscura サーバーで制御されます

使用例：

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	取得できる内容
"text"	プレーンテキスト。HTML タグ、スクリプト、スタイルを除去します
"markdown"	整形された Markdown。Obscura ネイティブの LP.getMarkdown CDP を使用します
"html"	HTML マークアップ
"links"	すべての href 値（1 行に 1 つ）
"cookies"	名前、値、ドメイン、パス、有効期限を含む Cookie
"axtree"	アクセシビリティツリー。すべての要素のロール、名前、値を含みます
"layout"	ビューポートの指標。寸法、スクロールオフセット、デバイススケールを含みます

eval を指定すると、JavaScript の実行結果が、--- eval --- の区切りの下に出力形式の内容とともに追加されます。

---

browse_interact — 1 回の呼び出しでページを操作する

ページ上の要素をクリックするか、テキストを入力します（複数ステップの操作（ログイン → 待機 → 抽出）には、代わりに browse_session を使用してください）。

パラメーター	型	デフォルト	説明
url	string	—	アクセスする URL
action	"click" | "type"	—	実行する操作
selector	string	—	対象要素の CSS セレクター
text	string	—	入力するテキスト（action が "type" の場合は必須）
cookies	array	—	注入する Cookie [{name, value, ...}]
stealth	boolean	true	互換性のために受け付けます。ステルス機能は Obscura サーバーで制御されます

使用例：

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")

どちらの操作も新しいページを作成し、操作を実行してからページを閉じます。ページコンテキストは保持されません。フォームに入力してから送信ボタンをクリックするなど、連続した操作には browse_session を使用してください。

---

browse_session — 複数ステップの永続セッション

永続的なブラウザーセッションを作成し、複数回の呼び出しにわたって操作してから閉じます。セッションは5分間操作がないと自動的に閉じます。複数のセッションを同時に実行できます。

パラメーター	型	必須となる条件	説明
action	"create" | "close" | "list" | "goto" | "wait" | "extract" | "click" | "type"	すべて	実行する操作
session_id	string	create、list 以外のすべて	create で取得したセッション ID
url	string	create、goto	移動先の URL
selector	string	wait、click、type	CSS セレクター
expression	string	wait（セレクターがない場合）、extract	JavaScript 式
text	string	type	入力するテキスト
timeout	number	wait（任意）	最大待機時間（ミリ秒）。デフォルトは30000、最大は120000
user_agent	string	create、goto	ナビゲーション時に使用するユーザーエージェント文字列を上書きします
headers	object	create、goto	追加の HTTP ヘッダー {key: value, ...}
clear_cookies	boolean	create	セッション作成時にブラウザーの Cookie をすべて削除します

セッションのライフサイクル：

action	動作	戻り値
create	新しいブラウザータブを開きます。必要に応じて Cookie を削除します。	セッション ID
close	タブとすべてのリソースを解放します。何度実行しても安全です。	確認メッセージ
list	すべてのアクティブなセッションとタイムスタンプを表示します。	セッション一覧
goto	新しい URL に移動します。ページは開いたままです。	確認メッセージ
wait	CSS セレクターが存在するか、JS 式が true を返すまでポーリングします。	確認メッセージ
extract	JavaScript を評価し、結果を返します。	評価結果
click	CSS セレクターで指定した要素をクリックします。	座標
type	入力フィールドにテキストを入力します。	確認メッセージ

ログインフローの例：

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")

複数記事の閲覧例：

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 — 並列一括スクレイピング

分離されたワーカープロセスを使用して、複数の URL を同時にスクレイピングします。各 URL には専用のヘッドレスブラウザーワーカーが割り当てられます。Obscura のネイティブな scrape コマンドを obscura-worker と組み合わせて構築されています。

パラメーター	型	デフォルト	最大	説明
urls	string[]	—	1000	並列スクレイピングする URL
eval	string	—	—	各ページで評価する JavaScript 式
concurrency	number	10	100	並列ワーカープロセス数
timeout	number	60	300	ワーカーごとのタイムアウト（秒）

例：

browse_scrape(urls: ["https://news.ycombinator.com", "https://example.com"], eval: "document.title", concurrency: 25)

出力形式（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
    }
  ]
}

エラー（タイムアウト、ネットワーク障害など）が発生した場合、URL ごとの結果には "eval" の代わりに "error" フィールドが含まれます。

{
  "url": "https://slow-site.com",
  "error": "timeout",
  "time_ms": 60000
}

このツールは、ヘッドレス Chrome に対する Obscura の中核的な優位性である、ステルス機能を内蔵した軽量な並列スクレイピングを直接活用します。ワーカーあたり約30 MBのメモリ使用量のため、100個のワーカーを同時に実行しても、Chrome のインスタンスを1つ実行するよりメモリ使用量が少なくなります。

設定

Claude Desktop / Cline / Continue / 任意の MCP クライアント

{
  "mcpServers": {
    "obscura-mcp": {
      "command": "obscura-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

VS Code（Cline 拡張機能）

{
  "servers": {
    "obscura-mcp": {
      "command": "obscura-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

npm をグローバルにインストールすると、obscura-mcp が PATH 上で利用できるようになり、絶対パスは不要です。

環境変数

変数	デフォルト	説明
OBSCURA_PATH	—	カスタム Obscura バイナリへのパス
OBSCURA_STEALTH	—	ステルスモード（検出回避）を有効にします
OBSCURA_PROXY	—	すべてのトラフィックに使用するプロキシ URL
OBSCURA_USER_AGENT	—	デフォルトのユーザーエージェントを上書きします
MCP_HTTP_HOST	127.0.0.1	HTTP トランスポートのホスト
MCP_HTTP_PORT	3000	HTTP トランスポートのポート
MCP_TRANSPORT	stdio	トランスポートモード：stdio または streamable-http
OBSCURA_STARTUP_TIMEOUT_MS	15000	Obscura CDP の起動を待つ時間（ミリ秒）
OBSCURA_NAVIGATION_WAIT_MS	3000	ページ遷移後に待機する時間（ミリ秒）
CDP_REQUEST_TIMEOUT_MS	10000	CDP の応答を待つ時間（ミリ秒）

開発

TypeScript で構築し、dist/ にコンパイルして、Vitest でテストしています。

git clone https://github.com/Metadrama/obscura-mcp
cd obscura-mcp
npm install
npm run build
npm test

36 件すべての統合テストは、実際の Obscura バイナリ（初回実行時に自動ダウンロード）に対して実行されます。テストでは StdioClientTransport を使用し、すべてのツール、形式、アクションを網羅しています。

Obscura を選ぶ理由

• Chrome 不要 — 純粋な Rust 製で、200 MB のブラウザーバンドルは不要です
• CDP ネイティブ — Chrome DevTools Protocol を直接公開します
• 検出回避 — スクレイピング対策サイト向けのステルス機能を内蔵しています
• 小さなフットプリント — 約 15 MB のバイナリで、数ミリ秒で起動します

ライセンス

MIT