Introduction

The DSH desktop client and various MCP clients commonly face API key limits, paywalls, or incomplete functionality when handling web tasks. hermes-web-mcp is a keyless MCP server. It implements web search, content extraction, and real browser automation through a local service chain, and basic web interaction tasks can be completed without calling external paid APIs.

Plugin Overview

hermes-web-mcp is an MCP (Model Context Protocol) server maintained by ShadowMiner under the MIT license. It provides DSH and other MCP clients with a complete web toolset, with core value in being “keyless” and “locally rendered”.

Core Capabilities

The plugin provides 9 tools, divided into three categories:

  1. Web search: web_search
    • Searches by connecting directly to cn.bing or DuckDuckGo, without requiring a search API key.
  2. Web extraction: web_extract
    • Renders pages using the local playwright-service, then converts them to Markdown with html-to-md, without requiring a scraping API key.
  3. Real browser automation: page_* series (7 tools total)
    • Uses CDP (Chrome DevTools Protocol) to connect to a shared Chrome instance in isolated contexts, without interfering with the host browser’s tabs.

Working Principle

The server depends on three local components to form a processing chain:

  • Playwright Service: Responsible for rendering web pages and exposing the /scrape endpoint.
  • HTML-to-MD Service: Responsible for converting HTML to Markdown and exposing the /convert endpoint.
  • CDP Chrome instance: Provides a real browser environment, with two instances, direct (port 9333) and proxy (port 9334), for different network environments.

web_extract first tries CDP rendering, and automatically falls back to plain fetch if that fails. The page_* tools connect to the same Chrome instances through playwright chromium.connectOverCDP, ensuring operations run in an isolated environment.

Environment Variables

Configure the following environment variables before running; default values are as follows:

Variable Default Description
WEBMCP_PW D:/path/to/playwright-service/node_modules/playwright Playwright installation path, used for connectOverCDP
WEBMCP_SCRAPE http://127.0.0.1:3003/scrape Playwright Service scraping endpoint
WEBMCP_CONVERT http://127.0.0.1:8080/convert HTML-to-Markdown conversion endpoint
WEBMCP_CDP_DIRECT http://127.0.0.1:9333 Direct CDP Chrome endpoint
WEBMCP_CDP_PROXY http://127.0.0.1:9334 Proxy CDP Chrome endpoint

Deployment Prerequisites

Before configuring DSH, ensure the local environment meets the following dependencies:

  1. Node.js: version must be >= 22.
  2. playwright-service: a locally running scraping service.
  3. html-to-md: a locally running conversion service.
  4. CDP Chrome instances: start two Chrome instances listening on ports 9333 and 9334 (direct and proxy modes supported).
  5. Playwright installation: the chromium driver must exist at the path specified by WEBMCP_PW.

Configuration Examples

In the MCP client (for example, Claude Desktop), configure the server name as 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"
      }
    }
  }
}

Insert a record into DSH’s SQLite registry (fields should be adjusted according to the actual table structure):

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

Typical Usage

After all prerequisite services are running, you can test with the following command:

node smoke.js

Tool call examples:

  • Search: web_search("DeepSeek", max_results=5)
  • Extract: web_extract("https://example.com", via_proxy=false, wait_ms=2500)
  • Automate:
    • page_open("https://example.com")
    • page_type("#input", "test", enter=true)
    • page_shot(full_page=true)
    • page_read()

Notes

  • Permission isolation: The page_* tools run in isolated contexts and do not touch the host browser’s tabs.
  • Dependency completeness: The plugin depends on the availability of multiple local services (playwright-service, html-to-md, and CDP Chrome).
  • Source code review: The plugin runs with the permissions of the current process; it is recommended to review the source code and license before enabling it.

This plugin aims to provide lightweight web interaction capabilities, suitable for development scenarios that require local processing and need to avoid API key restrictions. More details are available in the GitHub repository: https://github.com/ShadowMiner/hermes-web-mcp