Obscura MCP 服务器——给 AI Agent 装上浏览器

当 AI 需要浏览器

大语言模型的知识有截止日期、无法访问私有系统、无法执行操作。MCP（Model Context Protocol）为 AI 提供了工具调用能力，而 Obscura 的 MCP 服务器就是让 AI 拥有"浏览器"这个工具。

配置完成后，AI 可以：

• 打开网页并阅读正文
• 填写表单并登录
• 点击按钮和链接
• 提取页面内容和链接
• 管理 Cookie 和浏览器状态

启动 MCP 服务器

两种传输模式：

# stdio 模式（默认，用于 Claude Desktop 本地集成）
obscura mcp
 
# HTTP 模式（远程或容器部署）
obscura mcp --http --port 8080
 
# 启用反检测
obscura mcp --stealth
 
# 配合代理
obscura mcp --stealth --proxy http://proxy.16yun.cn:8888

HTTP 传输默认绑定 127.0.0.1。在容器或 sidecar 部署中需要从外部访问时，用 --host 0.0.0.0 绑定全部网卡：

obscura mcp --http --host 0.0.0.0 --port 3000

配置 Claude Desktop

编辑配置文件：

{
  "mcpServers": {
    "obscura": {
      "command": "/path/to/obscura",
      "args": ["mcp", "--stealth"]
    }
  }
}

macOS 配置文件位置：~/Library/Application Support/Claude/claude_desktop_config.json，Windows 在 %APPDATA%\Claude\claude_desktop_config.json。

配置 Claude Code：

claude mcp add obscura /path/to/obscura mcp

重启客户端后，Obscura 的浏览器工具会出现在可用工具列表里。

浏览器工具一览

Obscura MCP 服务器暴露了 30+ 个浏览器工具，覆盖导航、读取、交互、等待、JS 执行、Cookie、标签页等类别。理解工具的分工，是组合出复杂工作流的基础——MCP 工具是细粒度的，AI 需要按"导航→读取/交互→等待→再读取"的节奏串起来。

导航类

页面读取类

交互类

等待与 JavaScript

Cookie 与 Storage

Tab 管理

实战示例：AI 自动搜索

完整的 AI Agent 工作流示例：

1. browser_navigate → 打开搜索引擎
2. browser_fill → 输入搜索关键词
3. browser_press_key → 按回车
4. browser_wait_for → 等待搜索结果加载
5. browser_snapshot → 阅读搜索结果摘要
6. browser_click → 点击感兴趣的链接
7. browser_markdown → 提取页面内容为 Markdown
8. browser_network_requests → 检查 API 调用

这个流程体现了 MCP 的核心价值：每一步都是 AI 在观察上一步结果后自主决策的。脚本化的 Puppeteer 做不到这一点——它只能按预设逻辑执行，遇到页面结构变化就中断；而 AI Agent 可以在 browser_snapshot 后读懂"这一页是验证码"或"结果是空的"，自己决定重试还是换路径。

会话状态管理

MCP 工具操作的是当前浏览器会话，这一点和 CDP 模式一致。几个关键认知：

• 导航先行：browser_snapshot、browser_click、browser_extract 都作用于当前页，所以工作流的第一步几乎总是 browser_navigate。
• 认证状态可持久化：用 browser_storage_state 导出 Cookie + localStorage，下次会话用 browser_set_storage_state 恢复，避免每次都走登录流程。配合 --storage-dir 启动参数，状态还能落盘跨进程保留。
• 多标签并行：browser_tab_new + browser_tab_switch 让 AI 在多个页面间切换，适合"在 A 页查信息、去 B 页填表"的跨站工作流。

HTTP 模式的安全配置

HTTP 传输模式下，Obscura 内置两层安全保护。

Origin 白名单：

OBSCURA_MCP_ALLOWED_ORIGINS="https://app.16yun.cn" \
  obscura mcp --http --host 0.0.0.0 --port 3000

设置后，只有指定 Origin 的浏览器页面可以访问 MCP 接口。原生 MCP 客户端不发送 Origin，始终允许。未设置（默认）则保持宽松。这一层主要用于阻止恶意网页跨域 POST 到本地 MCP 端口。

请求体上限：单次请求体上限 16 MB，防止未认证调用者通过超大请求消耗内存。

当你把 HTTP 传输暴露到回环地址之外时，务必设置 Origin 白名单，并放在强制认证的反向代理或网络隔离之后。

与 Stealth 和 Proxy 组合

obscura mcp \
  --stealth \
  --proxy http://user:pass@proxy.16yun.cn:8888 \
  --user-agent "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ..."

AI Agent 发起的每个浏览器操作都通过 Stealth 反检测和代理出口。对爬虫类任务来说，这一层不可或缺——没有 Stealth 的 MCP 会话很容易被目标站的被动检测识别为自动化流量。

比传统浏览器自动化更上层

对比 Puppeteer 脚本和 MCP AI Agent 两种方式：

需要权衡的一点：AI Agent 的非确定性意味着同样的输入可能走出不同的步骤路径。对要求可复现的批处理任务，确定性脚本（CDP 或 CLI）仍然更合适；MCP 的优势在于一次性、探索性、面对未知页面结构的工作。

总结

Obscura MCP 服务器是 AI Agent 和网页之间的标准桥梁。30+ 个工具覆盖了浏览器自动化的全部基本操作，配合 Stealth 和代理配置，AI Agent 可以像真实用户一样浏览网页、提取数据、执行操作。它最适合的是探索性、容错要求高、页面结构不确定的任务；对确定性批处理，CLI 和 CDP 仍是更稳妥的选择。