mcpsurfr
Local web search for an agent with no API keys: results are ranked on your machine and only the relevant passages come back
- 151 ★ on the repository
- Last commit
Extended access
Why this level
- Pages are fetched with browser impersonation and site terms may forbid automated access
- Queries go to external search engines and are visible to them
Install
- Works in
Manual install
uvx mcpsurfrStarts the server over stdio, the version is cached on first run.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Pages are fetched with browser impersonation and site terms may forbid automated access
- Queries go to external search engines and are visible to them
This is third-party code. Review the repository files before installing.
What it does
mcpsurfr searches the web through the ddgs library, which queries several search engines without keys and skips blocked ones. A small MobileBERT model on plain numpy then re-ranks results on the device, and the server fetches only the best pages. They are cut down to main text without menus, banners and footers, PDFs are read from the text layer, and sites with markdown copies are read from those. There are four tools: `search` returns only the passages that answer the question, about a tenth of the tokens; `rag_search_ddgs` returns whole pages; `deep_research` merges several queries; `read_url` reads one page, and with `query` only the relevant spots. Stack Exchange, Wikipedia, GitHub, Hacker News, PyPI, npm and crates.io are read through their free APIs. The answer lists skipped pages with a reason.
Who it is for. Developers who want to give an agent web search without paid keys and without wasting context tokens.
Good fit when
- The agent needs fresh library docs and gets five answering passages instead of ten pages
- Research on a topic takes several queries and `deep_research` merges them without duplicates
- You need a Stack Overflow answer with the accepted solution first, not the whole thread
- You have no search API keys and do not want to pay for them
Not a fit when
- You need stable results for production load: search goes through public engines that block frequent requests
- You need to read pages built entirely on JavaScript: such pages land in the skipped list
- You need search over private company data: the server searches the open web only
Example request
Find how to configure lifespan in the latest FastAPI and show only the answering passages with page linksMCP
- Transport
- stdio
- Authentication
- not required
Limitations
Google often blocks requests and the server falls back to `auto` mode by itself. Pages closed to scrapers or built wholly on JavaScript, plus Reddit threads and msn.com articles, land in the skipped list with a link and snippet. Pages are fetched with browser impersonation, and some sites forbid automated access in their terms, which stays on the user. Searches and pages are cached for five minutes. The ranking model is loaded on first run. The project was formerly called `mcp-local-rag`. The license is MIT and installation is through `uvx` or Docker from ghcr.io.
How to disable. Remove the server registration in the client (`claude mcp remove mcpsurfr`) and the `uv` cache if you installed through `uv tool install`.
FAQ
Are API keys required?
No, search goes through ddgs without keys and ranking runs on a local MobileBERT model on your machine.
How do I connect it to Claude Code?
With `claude mcp add mcpsurfr -- uvx mcpsurfr`. A version is pinned as `mcpsurfr@<version>` and `mcpsurfr@latest` takes the newest release on every start.
How does `search` differ from `rag_search_ddgs`?
`search` returns only relevant passages, about a tenth of the tokens, while `rag_search_ddgs` returns whole pages in the original mode.
Does the server read PDFs?
Yes, from the text layer, the first 50 pages. Scans without a text layer are not recognized.
What if Google blocks the search?
Nothing special: the server switches to `auto` mode on its own, which queries several engines and skips blocked ones. Warnings land in the `warnings` field.
Discussion
No questions or reviews yet.
Related
MCP serversA local MCP server with no API keys: multi-engine web search, page fetching and document reading tuned for LLMs.
Web search via DuckDuckGo and page reading for the agent with no API keys, with built-in rate limiting
A web search MCP server that gives the agent full page text at once: Stack Overflow answers, GitHub threads, arXiv papers
A metasearch MCP server: the agent searches text, images, news, videos and books across many engines and extracts page content
Local web search for agents: searches, reads pages and returns compact passages with sources, saving context tokens
An MCP server that searches Google and Scholar, reads pages and PDFs and stores findings in a local project knowledge graph
README in short
A short description, a flow chart from query to passages, a feature list with no keys and local ranking, a table of four tools, configs for `uvx` and Docker and a table of optional settings.