ExperimentalZsh · MCP · Web search

zfetch

Give your agent two tools for the web.

Search with SearXNG, then read a page as Markdown. zfetch is a Zsh MCP server that connects the fetching, JSON, HTML cleaning, and conversion tools into one stdio interface for an agent.

View on GitHub

Search, then read

search

Send a query to your SearXNG instance. Get the complete JSON result, including search results, suggestions, infoboxes, and engine errors. Page, language, time range, and safe-search options are available.

{"query":"Zsh documentation","language":"en"}

get

Fetch an HTML page, clean it with zoup, and convert it with zhtml2md. Return Markdown, with the final URL available separately for resolving relative links.

{"url":"https://www.zsh.org/"}

Small tools, joined together

search → zcurl → SearXNG → JSON
get    → zcurl → zoup → zhtml2md → Markdown

zcurl handles HTTP and HTTPS, zjson handles JSON, zoup cleans HTML, and zhtml2md produces Markdown. The server needs no jq, Python, Node.js, external curl command, or MCP SDK at runtime. HTTPS uses the native zcurl module linked to libcurl.

Connect an MCP client

Place the four dependency checkouts beside zfetch and build zcurl for the Zsh binary you will run. Set your SearXNG JSON search endpoint, then validate the setup with bin/zfetch --check.

{
  "mcpServers": {
    "zfetch": {
      "command": "zsh",
      "args": ["-df", "/absolute/path/to/zfetch/bin/zfetch"],
      "env": {
        "ZFETCH_SEARCH_URL": "https://your-searxng.example/search"
      }
    }
  }
}

Replace the example endpoint with your instance and enable JSON output in SearXNG. Clients may display the tools as zfetch.search and zfetch.get; their MCP names are search and get.

Current scope

This initial implementation uses newline-delimited JSON-RPC over stdio and processes requests sequentially. It has been verified locally on Zsh 5.9.2. Page reading supports UTF-8 HTML/XHTML, follows up to five redirects, and caps response bodies at 1 MiB. It reads the returned HTML without executing JavaScript or extracting an article.

Back to The Lab