Hive Web

Русская версия

Hive Web is a local MCP server for agents that need web access without flooding the model with raw pages. It gives Hermes, Claude Code, Codex, OpenCode, and other MCP clients a small set of tools for search, page extraction, and controlled browser sessions.

The server is built around two paths:

static-web   cheap search and page extraction through SearXNG and Firecrawl
action-web   live Playwright sessions with compact snapshots and safe actions

Static tools handle normal research. Action tools are for sites that need a browser, forms, or navigation. Both return compact, structured data and store larger payloads as local artifacts.

Naming

The project is called Hive Web. The GitHub repository is hive-web.

The Python package and executable are named hive-web-runtime because they run the local MCP server. MCP clients usually register that server as hive_web.

GitHub repository   hive-web
Python package      hive-web-runtime
CLI command         hive-web-runtime
MCP server name     hive_web
Python module       hive_web_runtime

Related MCP server: Local-MCP-server

Tools

Static tools:

• static_web_search(query, limit=5, max_tokens=2000)

• static_web_extract(url, max_tokens=3000, format="markdown")

• static_web_get_artifact(artifact_id, name="content.md")

Browser tools:

• action_web_session_create(name?, headless?)

• action_web_navigate(session_id, url? | search_query?)

• action_web_snapshot(session_id, max_tokens=1200)

• action_web_click(session_id, ref? | selector?, confirm_sensitive=false)

• action_web_type(session_id, text, ref? | selector?, clear=true)

• action_web_press(session_id, key)

• action_web_close(session_id)

Requirements

• Python 3.11+

• uv

• Local or remote SearXNG endpoint

• Local or remote Firecrawl endpoint

• Playwright browsers for action-web sessions

Default endpoints:

SEARXNG_URL=http://localhost:8888
FIRECRAWL_API_URL=http://localhost:3002
HIVE_WEB_ARTIFACT_DIR=~/.cache/hive-web-runtime/artifacts

If you already run SearXNG and Firecrawl somewhere else, set those environment variables before starting the MCP server.

Install

git clone https://github.com/YegorMy/hive-web.git
cd hive-web
uv run playwright install chromium
bash scripts/install-hermes-mcp.sh

The installer runs uv sync, writes a hive_web entry into ~/.hermes/config.yaml, and tests the MCP connection. The Playwright install step is needed for action_web_* browser tools; static_web_* tools only need SearXNG and Firecrawl.

After changing MCP config, reload MCP in your client or start a new session.

/reload-mcp

Manual server start, mostly useful for debugging:

uv run hive-web-runtime

The server speaks MCP over stdio, so it waits for an MCP client.

Development checks

Run the unit tests:

HIVE_WEB_ARTIFACT_DIR=/tmp/hive-web-runtime-artifacts uv run pytest -q

Run a live MCP smoke test. This requires Firecrawl to be reachable at FIRECRAWL_API_URL:

uv run python scripts/test-mcp-client.py

Hermes setup

If you skipped the install script above, run it from the cloned repository:

bash scripts/install-hermes-mcp.sh

You can override the server name and endpoints:

SERVER_NAME=hive_web \
SEARXNG_URL=http://localhost:8888 \
FIRECRAWL_API_URL=http://localhost:3002 \
bash scripts/install-hermes-mcp.sh

Manual Hermes config:

mcp_servers:
  hive_web:
    command: /absolute/path/to/uv
    args: ["run", "--project", "/absolute/path/to/hive-web", "hive-web-runtime"]
    env:
      SEARXNG_URL: "http://localhost:8888"
      FIRECRAWL_API_URL: "http://localhost:3002"
      HIVE_WEB_ARTIFACT_DIR: "/absolute/path/to/artifacts"
    connect_timeout: 60
    enabled: true

After changing MCP config, reload MCP in the client or start a new session.

Other MCP clients

Claude Code:

claude mcp add -s user hive_web -- uv run --project /absolute/path/to/hive-web hive-web-runtime

Codex CLI:

codex mcp add hive_web -- uv run --project /absolute/path/to/hive-web hive-web-runtime

OpenCode uses the same stdio command in its MCP config:

{
  "mcp": {
    "hive_web": {
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/hive-web", "hive-web-runtime"]
    }
  }
}

Safety model

Hive Web tries to keep browser automation boring and predictable:

• Search and extraction return compact markdown or structured JSON, not full raw HTML by default.

• Larger payloads go into the artifact store and can be fetched by artifact_id.

• Browser snapshots expose refs like @1 and @2 instead of dumping the full DOM.

• action_web_click blocks payment, password, 2FA, and CAPTCHA-looking targets unless the caller explicitly confirms the action.

This is not a CAPTCHA bypass tool, a shopping bot, or a payment automation layer. Treat it as read/search/extract plus careful browser control.

Ozon egress routing

Hive Web can update host routes before opening URLs that match configured domains.

Default config file:

~/.config/hive-web-runtime/egress-routes.json

The default file is auto-created on first use and includes:

{
  "enabled": true,
  "refresh_interval_seconds": 3600,
  "rules": [
    {
      "name": "ozon-direct",
      "enabled": true,
      "domains": ["ozon.ru", "www.ozon.ru", ".ozon.ru"],
      "resolve_hosts": ["ozon.ru", "www.ozon.ru"],
      "gateway": "auto",
      "interface": "auto",
      "strict": false
    }
  ]
}

State cache path:

~/.cache/hive-web-runtime/egress-routes-state.json

Route checks and updates happen on startup/refresh and when the state is older than refresh_interval_seconds. On non-macOS platforms this gate is a safe no-op and returns structured warnings.

hive-web-egress-routes status
hive-web-egress-routes ensure --force --url https://www.ozon.ru
./scripts/update-egress-routes.sh

Route commands are executed through system route, so updates can require helper privileges (for example, running via sudo or a launchd helper). To keep Ozon routes fresh on macOS, install the LaunchDaemon helper once:

sudo bash scripts/install-ozon-direct-bypass.sh

The Ozon installer writes/updates the ozon-direct rule in egress-routes.json, installs the periodic LaunchDaemon, and immediately runs a privileged route refresh. The helper refreshes every 5 minutes by default.

The safe behavior is:

Anthropic / OpenAI / Claude Code -> VPN route such as utun*
Ozon host IPs                   -> normal local interface/gateway such as en0

Verify after install or after reconnecting your VPN:

route -n get 185.73.193.68
route -n get 185.73.194.82

If Ozon routes show utun*, rerun the installer or wait for the LaunchDaemon refresh. Reconnecting a VPN may replace host routes on some setups. If you ran an older Ozon helper and API traffic starts going direct instead of through the VPN, reconnect the VPN once to restore its broad split routes, then rerun this fixed installer.

Remove the Ozon helper with:

sudo LABEL=com.hive-web-runtime.egress-routes.ozon bash scripts/uninstall-egress-routes-launchdaemon.sh

This only updates local routes for configured domains. It does not bypass CAPTCHA, log in, add items to cart, or automate checkout.

Development

uv sync
HIVE_WEB_ARTIFACT_DIR=/tmp/hive-web-runtime-artifacts uv run pytest -q
uv run python scripts/test-mcp-client.py
uv run python scripts/smoke-action-web.py

Use a temporary artifact directory for tests if your normal cache directory is not writable in the current environment.

License

MIT