ask-web-search-mcp

Gem Version

A minimal MCP (Model Context Protocol) server that exposes an ask_web_search tool backed by SearXNG. Designed for use with MCP-compatible clients like ZCode, Claude Code, Codex, and others.

The server speaks MCP dual-mode (requires ask-mcp >= 0.4): it negotiates the stateless 2026-07-28 revision via server/discover (no initialize handshake, per-request _meta, resultType) when the client supports it, and falls back to the legacy initialize handshake for older clients.

The tool was renamed from web_search to ask_web_search in version 0.2.0 to avoid collisions with client-side tools. Use ask_web_search in your configuration and prompts.

Prerequisites

A running SearXNG instance. The default endpoint is http://localhost:8888.

docker run -d --name searxng -p 8888:8080 searxng/searxng

Or use the provided docker-compose.yml in the searxng directory of this repository:

cd searxng
docker compose up -d

Installation

gem install ask-web-search-mcp

Or in your Gemfile:

gem "ask-web-search-mcp"

Usage

Standalone

ask-web-search-mcp

The server reads JSON-RPC messages on stdin and writes responses to stdout (the standard MCP stdio transport).

With ZCode

Add to your ZCode user configuration (~/.zcode/v2/config.json or ~/.zcode/cli/config.json):

{
  "mcp": {
    "servers": {
      "ask-web-search-mcp": {
        "type": "stdio",
        "command": "ask-web-search-mcp",
        "args": []
      }
    }
  }
}

After restarting ZCode, the ask_web_search tool will be available to the model automatically.

With Claude Code

claude mcp add ask-web-search-mcp -- npx -y @anthropic-ai/mcp-serve ask-web-search-mcp

Configuration

  • SEARXNG_URL - the SearXNG endpoint (default: http://localhost:8888).
  • DEBUG=1 - enable verbose logs on stderr.

Full documentation

The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. Core: Web Search covers ask-web-search-mcp in depth, including the tool library and troubleshooting. API reference: https://ask-rb.github.io/ask-docs/reference/api.

Development

bundle install
bundle exec rake test

ask-mcp resolves from rubygems (>= 0.4 — the 0.4 line carries the stateless 2026-07-28 protocol support). The suite drives the server end-to-end with Ask::MCP::Client over a real stdio subprocess, stubbing SearXNG in-process (no network required).

License

MIT