mcpsurfr 1.2.3

Local web search for your LLM over MCP. No API keys, and results are ranked on your machine. Formerly mcp-local-rag.

flowchart LR
    Q["query + keywords"] --> S["ddgs<br>several engines, no keys"]
    S --> R["re-rank<br>on device"]
    R --> F["fetch top pages<br>main text, PDFs"]
    F -->|search| P["best passages<br>~1k tokens"]
    F -->|rag_search_ddgs<br>deep_research| W["full pages<br>shared budget"]

What's in it:

• No API keys. Searches go through ddgs. Its auto mode asks several engines at once and skips blocked ones.
• Ranked locally. A small MobileBERT model on plain numpy re-ranks results, so only the best pages get fetched.
• Clean text. Pages are fetched with browser impersonation, and only the main content is kept: no menus, cookie banners or footers. Code blocks and tables keep their lines. PDFs are read too (text layer, first 50 pages). The same page under two URLs comes back once.
• Passages instead of pages. search returns just the paragraphs that answer the question, about a tenth of the tokens. When nothing matches well, it can ask you whether you want the full pages instead.
• Says what it left out. Results list skipped pages with a reason (blocked, JavaScript-only, duplicate...), cut pages are marked truncated, and fallbacks and engine failures show up as warnings. Google blocks often, so it falls back to auto on its own.
• Brings its own guide. It serves a skill and a research prompt, so clients pick up how to use it without setup.

The search tools also take recency (day, week, month, year), region (uk-en, de-de...), include_domains / exclude_domains, and news: true for dated news articles.

The old rag_search_google, deep_research_ddgs and deep_research_google presets are hidden by default. Options says why and how to turn them back on.

Backends: auto (default), brave, duckduckgo, google, grokipedia, mojeek, startpage, wikipedia, yahoo. auto and brave are the dependable ones. With news: true: auto, bing, duckduckgo, yahoo.

How it compares

Other keyless MCP servers (mcp-searxng, duckduckgo-mcp-server, open-webSearch, the official fetch server) hand the model snippets or whole pages. Hosted APIs like Tavily, Exa and Brave do cut pages down to the useful parts, but they need a key and do it on their servers. mcpsurfr does that part on your machine:

• picks passages with BM25 on the query plus keywords the model supplies, and an on-device embedder for ties and paraphrases
• drops near-duplicate pages and shares one text budget across the rest
• tells the model what it skipped and why, and can ask you before falling back to full pages

What it doesn't do: JavaScript-only pages, OCR for scanned PDFs, image search.

Install

From PyPI with uv:

{
  "mcpServers": {
    "mcpsurfr": {
      "command": "uvx",
      "args": ["mcpsurfr"]
    }
  }
}

uvx keeps using the version it cached first. Use "mcpsurfr@latest" to pick up new releases on every start (about a second slower), or "mcpsurfr@<version>" to pin one. uv tool install mcpsurfr works too, with "command": "mcpsurfr".

Or with Docker (amd64 and arm64):

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

Options

Both settings are optional and go in the server entry's env.

A normal setup only ever needs the budget, if anything:

{
  "mcpServers": {
    "mcpsurfr": {
      "command": "uvx",
      "args": ["mcpsurfr"],
      "env": {
        "MCPSURFR_MAX_CHARS": "80000"
      }
    }
  }
}

With the legacy tools, for prompts or workflows that still call them by name:

{
  "mcpServers": {
    "mcpsurfr": {
      "command": "uvx",
      "args": ["mcpsurfr"],
      "env": {
        "MCPSURFR_MAX_CHARS": "80000",
        "MCPSURFR_LEGACY_TOOLS": "1"
      }
    }
  }
}

Why they're off: they're just rag_search_ddgs and deep_research with a fixed backend, which the search tools now take themselves. Each tool's name, description and parameters get sent to the model in every chat whether it's used or not, so three duplicates cost context for nothing and give the model more ways to pick the wrong one.

With Docker, env only reaches the docker command, not the container. Pass the settings with -e in args instead, before the image name:

"args": ["run", "--rm", "-i", "--init", "-e", "MCPSURFR_MAX_CHARS=80000", "ghcr.io/nkapila6/mcpsurfr:latest"]

Add "-e", "MCPSURFR_LEGACY_TOOLS=1" the same way for the legacy tools.

Not sure where your config lives? See the MCP quickstart. Tested with Claude Desktop, Claude Code, Cursor and Goose.

Coming from mcp-local-rag? Your old config keeps working, since the old URL redirects and the mcp-local-rag command still exists. Switching to the config above gets you the new name and drops the --python=3.10 pin (3.10 is end of life as of October 2026). If your prompts call rag_search_google or deep_research_google by name, use the legacy config under Options.

Skill and prompt

The mcpsurfr-search skill tells the model which tool and backend to pick and how to cite. The server serves it as skill://mcpsurfr-search/SKILL.md, so most clients need nothing extra. To add it to Claude Desktop by hand: Settings → Skills → Add from folder, then pick src/mcpsurfr/skills/mcpsurfr-search/.

The research(topic) prompt plans a few search terms, runs deep_research and writes a cited summary.

Example

Asking Claude Desktop about something newer than its training data:

Security audit by MseeP · Issues and PRs welcome · MIT licensed · Buy me a coffee if it helps you