MCP Local Rag

What nkapila6/mcp-local-rag MCP server does

nkapila6/mcp-local-rag brings web search into MCP-compatible LLM clients without requiring API keys. Search requests use the ddgs package and can query several engines, while ranking and result selection happen locally. The server can return targeted passages, complete page text, or a consolidated research result assembled from multiple searches.

Its main search modes are:

• search returns relevant passages, with optional keyword hints, rather than entire pages.
• rag_search_ddgs retrieves full pages through DuckDuckGo-backed search and orders them by semantic relevance.
• rag_search_google performs the corresponding Google-backed search and can fall back to automatic engine selection when Google blocks a request.
• deep_research combines several search terms across selected backends, removes duplicates, and ranks the collected material.
• deep_research_ddgs and deep_research_google provide DuckDuckGo-only and Google-only shortcuts.

The server also provides a search skill and a research(topic) prompt. These help clients select tools and backends, plan multiple queries, and produce cited summaries.

How it works

The server first obtains search results through ddgs. In automatic mode, the package can try several engines and skip engines that are blocked. Search results are initially selected from their snippets, then pages may be fetched and divided into passages. Keyword matching uses BM25; when that is insufficient or returns too many candidates, a MobileBERT embedding model running with NumPy ranks passages by meaning.

Fetched pages are processed to retain their main content instead of navigation elements, cookie notices, or footers. Code blocks and tables preserve their lines. Duplicate pages found under different URLs are merged. The response includes page URLs and can identify skipped pages, truncation, fallback behavior, and engine failures through reasons or warnings.

Setup and configuration

A stdio configuration can run the server with uvx directly from the Git repository:

{
  "mcpServers": {
    "mcpsurfr": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]
    }
  }
}

Docker is also supported on amd64 and arm64:

{
  "mcpServers": {
    "mcpsurfr": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--init", "ghcr.io/nkapila6/mcpsurfr:latest"]
    }
  }
}

The project was tested with Claude Desktop, Claude Code, Cursor, and Goose. Existing mcp-local-rag configurations continue to work because the former URL redirects and the mcp-local-rag command remains available. The renamed configuration uses the mcpsurfr command and removes the former Python 3.10 pin.

Full-page tools use a 40,000-character limit per call by default. Set MCPSURFR_MAX_CHARS in the MCP server environment to change that limit, for example 80000.

Tools and capabilities

Supported research backends include automatic multi-engine selection, Brave, DuckDuckGo, Google, Grokipedia, Mojeek, Startpage, Wikipedia, and Yahoo. The available tool description also lists Bing and Yandex as selectable backends. DuckDuckGo is suitable for privacy-focused general searches, Google for broad or technical coverage, Wikipedia for encyclopedia-style facts, and multiple backends for wider coverage.

The deep_research workflow accepts multiple terms, aggregates results, ranks them, and removes duplicates. Full-page responses share the character budget, while passage-oriented search can substantially reduce the amount of text returned to the model. Search output can also indicate when a page was blocked, is a PDF, duplicated another result, or was truncated.

Limitations and notes

Web access still depends on the selected engines and the pages they expose. Google may block requests, in which case Google-backed search can fall back to automatic search. Some pages may be skipped because they are blocked, PDFs, duplicates, or otherwise unsuitable for extraction. The server is intended for local ranking and retrieval; its results are search context for an LLM rather than a guarantee of source completeness or correctness.

The project is MIT licensed and was formerly published under the mcp-local-rag name.