SourceWeave Web Search MCP server

SourceWeave Web Search

Search-first MCP server and CLI for web research.

<!-- mcp-name: io.github.MRNAQA/sourceweave-web-search -->

[!NOTE]

sourceweave-search-mcp is the default local entrypoint. When explicit SOURCEWEAVESEARCH endpoint variables are absent, it discovers or starts the local Docker-backed stack automatically. If you already run the services yourself, set explicit endpoints and it will use them instead.

Overview • Getting started • Managed local runtime • MCP client setup • CLI • Container deployments • OpenWebUI • Runtime configuration • Development

Overview

SourceWeave Web Search gives MCP clients a compact three-tool contract for web research:

• searchweb(query, domains?, urls?, effort?) discovers sources and returns compact results with stable pageid handles.
• readpages(pageids, focus?) reads stored pages by page_id.
• read_urls(urls, focus?) reads direct URLs without searching first.

It combines:

Getting started

Requirements

• Python 3.12+
• Docker with Compose support for the default managed local runtime
• Explicit SOURCEWEAVESEARCH endpoints only if you want hosted or self-managed services

Managed local runtime

Run the server from the published package:

uvx --from sourceweave-web-search sourceweave-search-mcp

Or start the MCP server over HTTP:

uvx --from sourceweave-web-search sourceweave-search-mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000

When no endpoint env vars are set, sourceweave-search-mcp:

Managed state lives under ~/.sourceweave-local/managed-runtime. Multiple MCP processes on the same machine share one managed stack per state directory.

[!IMPORTANT]

Managed runtime removes containers only when the last active SourceWeave-managed process exits. Named volumes are preserved, so cache data survives restarts. If the original owning process dies, a later process can recover the same stack from Docker project identity and persisted runtime state.

Explicit endpoint mode

If you already run SearXNG, Crawl4AI, and Redis or Valkey yourself, or want to point at hosted services, set explicit endpoints and the MCP entrypoint will bypass managed Docker startup:

SOURCEWEAVE_SEARCH_SEARXNG_BASE_URL="http://127.0.0.1:19080/search?format=json&q=<query>" \
SOURCEWEAVE_SEARCH_CRAWL4AI_BASE_URL="http://127.0.0.1:19235" \
SOURCEWEAVE_SEARCH_CACHE_REDIS_URL="redis://127.0.0.1:16379/2" \
uvx --from sourceweave-web-search sourceweave-search-mcp

Direct CLI

sourceweave-search runs the tool directly. Use it when the supporting services are already available or when you provide explicit endpoints. It does not start Docker.

Shortened. The full README is on GitHub.