hermes-web-mcp

给任意 MCP 客户端提供上网能力的 MCP server —— 无需任何 API key。

hermes-web-mcp 是一个 MCP(Model Context Protocol)server, 为 DSH Desktop 及任意 MCP 客户端提供完整的上网工具箱:

• web_search —— 免 key 搜索: cn.bing 直连, 失败自动切 DuckDuckGo(走代理); 无需搜索引擎 API key。
• web_extract —— 带 JS 渲染抓取任意网页(local playwright-service + html-to-md 链路, 双 CDP Chrome), 输出干净 Markdown。
• 7 个 page_* —— 在共享 CDP Chrome 的隔离上下文中操作真实浏览器(绝不触碰宿主浏览器标签页): page_open、page_click、page_type、page_read、page_shot、page_back、page_close。

工具列表

共 9 个工具: web_search + web_extract + 7 个 page_* 工具。

工作原理

┌──────────────┐   stdio (MCP)   ┌────────────────────── hermes-web-mcp ──────────────────────┐
│ MCP 客户端    │ ───────────────▶ │ web_search   → cn.bing(免 key) / DDG 兜底                  │
│ (DSH 等)     │                  │ web_extract  → playwright-service (:3003) → html-to-md    │
└──────────────┘                  │                (:8080)  ⇄ CDP Chrome 9333(直连) /          │
                                  │                9334(经 HTTP 代理)                          │
                                  │ page_*       → playwright chromium.connectOverCDP          │
                                  └───────────────────────────────────────────────────────────┘

web_extract 不需要任何抓取 API key: 本地 playwright-service 通过 CDP 渲染页面, html-to-md 服务把 HTML 转成 Markdown。背后是两个 Chrome 实例:

• CDP 直连(默认, 127.0.0.1:9333)—— 用于国内站点及带登录态的页面。
• CDP 代理(127.0.0.1:9334)—— 流量经本地 HTTP 代理出去的 Chrome, 用于海外/受限站点。

web_extract 优先走你指定的 CDP, 失败自动切换另一个; 都失败则降级为原生 fetch(无 JS 渲染)。page_* 工具用 Playwright 的 connectOverCDP 连接同一个共享 Chrome, 且运行在隔离上下文里——绝不触碰宿主浏览器的标签页。

环境变量

所有变量均可选——不设置时使用上面的默认值。

部署前置

1. Node.js ≥ 22, 并在本仓库执行 npm install(唯一运行时依赖: @modelcontextprotocol/sdk)。
2. playwright-service —— 提供 POST /scrape {url, wait_after_load, cdp_url} → {content, pageStatusCode, contentType} 的本地服务, 用 Playwright 对着目标 CDP 渲染页面。(firecrawl-lite 项目里有参考实现。)
3. html-to-md —— 提供 POST /convert {html} → {markdown} 的本地服务。
4. 两个 CDP Chrome 实例:
   • chrome --remote-debugging-port=9333(直连)
   • chrome --remote-debugging-port=9334(流量经本地 HTTP 代理出去, 用于海外/受限站点)。
5. 一个 WEBMCP_PW 能解析到的 Playwright 安装(或使用默认路径), 供 page_* 工具使用。

默认值假设服务监听 127.0.0.1:3003 / 127.0.0.1:8080, Chrome 在 9333 / 9334。环境不同? 直接设环境变量即可。

MCP 配置示例

通用 MCP 配置(如 Claude Desktop claude_desktop_config.json):

{
  "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-mcp-client(SQLite 注册表, insert 示例——列名请按你的表结构调整):

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'
  )
);

Smoke 测试说明

前置服务就绪后:

npm install
node smoke.js

smoke.js 通过真实 MCP stdio 拉起 server, 列出已注册工具, 然后依次调用 web_search、web_extract、page_open(代理)与 page_shot 并打印输出。需要 playwright-service、html-to-md 服务与两个 CDP Chrome 都在运行。

License

MIT —— Copyright (c) 2026 ShadowMiner。