Obscura MCP

obscura-mcp — 已归档

⚠️ 已归档。 上游从 v0.1.4 起提供原生 MCP（obscura mcp）。npm 包已弃用。

Obscura 的 MCP 服务适配器。Obscura 是一款轻量级的 Rust 无头浏览器，适用于网页抓取和 AI Agent 自动化。

通过简洁的 MCP 接口提供 Obscura 的原生 CDP 功能——无需依赖 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 传输方式。

工具

四种工具涵盖浏览网页、交互操作、会话持久化和批量抓取。

browse_page — 单次读取页面

一次调用即可获取任意页面的内容。可组合使用输出格式和可选的 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	—	覆盖浏览器的 user-agent 字符串
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 值——每行一个
"cookies"	Cookie 信息，包括名称、值、域、路径和过期时间
"axtree"	无障碍树——所有元素的角色、名称和值
"layout"	视口指标——尺寸、滚动偏移量、设备缩放比例

提供 eval 时，JavaScript 的执行结果会追加到格式化输出中，并置于 --- eval --- 分隔符下方。

---

browse_interact — 单次页面操作

点击页面中的元素，或在页面中输入文本。对于多步骤交互（登录 → 等待 → 提取），请改用 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	覆盖导航时使用的 user-agent 字符串
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 的结果会包含 "error" 字段，而不是 "eval"：

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

这是直接利用 Obscura 相较于无头 Chrome 的核心优势的工具：轻量级并行抓取，并内置隐匿功能。每个工作进程约占用 30 MB 内存，因此 100 个并发工作进程的内存占用低于单个 Chrome 实例。

配置

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	—	默认 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