Hermes Web MCP：免 Key 的网页搜索与自动化工具

前言¶

DSH 桌面端及各类 MCP 客户端在处理网页任务时，通常面临 API Key 限制、付费门槛或功能不全的问题。hermes-web-mcp 是一个 Keyless MCP 服务器，它通过本地服务链路实现了网页搜索、内容提取以及基于真实浏览器的自动化操作，无需调用外部付费 API 即可完成基础的网页交互任务。

插件简介¶

hermes-web-mcp 是一个 MCP (Model Context Protocol) 服务器，由 ShadowMiner 维护，采用 MIT 许可证。它为 DSH 及其他 MCP 客户端提供了一套完整的网页工具集，核心价值在于“免 Key”和“本地化渲染”。

核心能力¶

该插件提供 9 个工具，分为三类：

网页搜索：web_search
- 通过直接连接 cn.bing 或 DuckDuckGo 进行搜索，无需搜索 API Key。
网页提取：web_extract
- 通过本地 playwright-service 渲染页面，再经由 html-to-md 转换为 Markdown，无需抓取 API Key。
真实浏览器自动化：page_* 系列（共 7 个）
- 在隔离上下文中通过 CDP (Chrome DevTools Protocol) 连接共享的 Chrome 实例进行操作，不干扰宿主浏览器标签页。

工作原理¶

服务端依赖三个本地组件构成处理链路：

Playwright Service：负责实际渲染网页，暴露 /scrape 接口。
HTML-to-MD Service：负责将 HTML 转换为 Markdown，暴露 /convert 接口。
CDP Chrome 实例：提供真实浏览器环境，分为 direct (端口 9333) 和 proxy (端口 9334) 两个实例，用于处理不同网络环境。

web_extract 会优先尝试 CDP 渲染，失败后自动降级为普通 fetch。page_* 工具通过 playwright chromium.connectOverCDP 连接同一组 Chrome 实例，确保操作在隔离环境中进行。

环境变量¶

运行前需配置以下环境变量，默认值如下：

变量名	默认值	说明
`WEBMCP_PW`	`D:/path/to/playwright-service/node_modules/playwright`	Playwright 安装路径，用于 `connectOverCDP`
`WEBMCP_SCRAPE`	`http://127.0.0.1:3003/scrape`	Playwright Service 抓取接口
`WEBMCP_CONVERT`	`http://127.0.0.1:8080/convert`	HTML 转 Markdown 接口
`WEBMCP_CDP_DIRECT`	`http://127.0.0.1:9333`	直连 CDP Chrome 端点
`WEBMCP_CDP_PROXY`	`http://127.0.0.1:9334`	代理 CDP Chrome 端点

部署前置条件¶

在配置 DSH 之前，需确保本地环境满足以下依赖：

Node.js：版本需 >= 22。
playwright-service：本地运行的爬取服务。
html-to-md：本地运行的转换服务。
CDP Chrome 实例：启动两个 Chrome 实例，分别监听 9333 和 9334 端口（支持直连和代理）。
Playwright 安装：需在 WEBMCP_PW 指定的路径下存在 chromium 驱动。

配置示例¶

在 MCP 客户端（如 Claude Desktop）中，服务器名称配置为 hermes-web。

{
  "mcpServers": {
    "hermes-web": {
      "command": "node",
      "args": ["D:/path/to/hermes-web-mcp/hermes-web-mcp.js"],
      "env": {
        "WEBMCP_PW": "D:/path/to/playwright-service/node_modules/playwright",
        "WEBMCP_SCRAPE": "http://127.0.0.1:3003/scrape",
        "WEBMCP_CONVERT": "http://127.0.0.1:8080/convert",
        "WEBMCP_CDP_DIRECT": "http://127.0.0.1:9333",
        "WEBMCP_CDP_PROXY": "http://127.0.0.1:9334"
      }
    }
  }
}

在 DSH 的 SQLite 注册表中插入记录（需根据实际表结构调整字段）：

INSERT INTO mcp_servers (name, command, args, env) VALUES (
  'hermes-web',
  'node',
  JSON_ARRAY('D:/path/to/hermes-web-mcp/hermes-web-mcp.js'),
  JSON_OBJECT(
    'WEBMCP_PW',         'D:/path/to/playwright-service/node_modules/playwright',
    'WEBMCP_SCRAPE',     'http://127.0.0.1:3003/scrape',
    'WEBMCP_CONVERT',    'http://127.0.0.1:8080/convert',
    'WEBMCP_CDP_DIRECT', 'http://127.0.0.1:9333',
    'WEBMCP_CDP_PROXY',  'http://127.0.0.1:9334'
  )
);

典型用法¶

依赖所有前置服务运行后，可使用以下命令进行测试：

node smoke.js

工具调用示例：

搜索：web_search("DeepSeek", max_results=5)
提取：web_extract("https://example.com", via_proxy=false, wait_ms=2500)
自动化：
- page_open("https://example.com")
- page_type("#input", "test", enter=true)
- page_shot(full_page=true)
- page_read()

注意事项¶

权限隔离：page_* 工具运行在隔离上下文中，不会触碰宿主浏览器的标签页。
依赖完整性：插件运行依赖于本地多个服务（playwright-service、html-to-md、CDP Chrome）的可用性。
源码审查：插件以当前进程权限运行，建议在启用前检查源码与许可证。

该插件旨在提供轻量级的网页交互能力，适合需要本地化处理、规避 API Key 限制的开发场景。更多详情可查阅 GitHub 仓库：https://github.com/ShadowMiner/hermes-web-mcp