Install
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]Who It's For
MCPSurfr (formerly mcp-local-rag) is a local web search MCP server for LLMs: it needs no API keys, and search results are re-ranked on your own machine, with ranking handled by a small MobileBERT model running directly on numpy. It suits two kinds of users: those who want to add web retrieval to an MCP-capable client without signing up for a search service or managing keys, and agent workflows that need progressively deeper capabilities, from one-shot passage lookups to full-page text to multi-engine deep research.
Be clear about the prerequisites: you need a client that supports custom MCP servers and a machine that can run the uvx command — the official docs offer exactly one launch path, pulling the server up from GitHub via uvx. The official page does not say whether a hosted service or a graphical interface is offered, nor does it list operating system requirements or supported clients; if your environment does not allow pulling and executing code from GitHub, this main path won't work.
Your First Try in 3 Minutes
There is only one recommended main path, and both the command and the configuration come from the official instructions.
Prerequisite: your machine can run uvx, and your client supports configuring MCP servers by command/args. Step 1, write the official snippet into your client's MCP server configuration (where exactly to paste it varies by client):
"command": "uvx",
"args": ["--from", "git+https://github.com/nkapila6/mcpsurfr", "mcpsurfr"]
Step 2, save the configuration and reload the session; the client will launch mcpsurfr using that command. The first launch needs network access to pull the code from GitHub; the official docs say nothing about how long this takes or how caching behaves.
Step 3, call the search tool with a plain query term. It is an officially defined one-shot query that returns relevant passages and counts as a query-type operation; but calling it triggers a real web search and runs the re-ranking computation locally — "query" only means it performs no write operations, not that there are no network requests or privacy boundaries.
Success signals: the tool returns passage text relevant to your query, and the client's tool list shows rag_search_ddgs, rag_search_google, deep_research, deep_research_ddgs, and deep_research_google alongside search. The server also provides the skill resource skill://mcpsurfr-search/SKILL.md, whose exact purpose the official page does not elaborate on.
Use Cases
Case 1: Adding quick lookup retrieval to a conversation. Scenario: you are discussing a topic that may have new developments in your client, and you let the model call search first. It runs a one-shot query and returns relevant passages that the model can cite directly; because no API keys are needed, connecting from a new environment requires no sign-up with any search service. What can be confirmed ends at the return of relevant passages; the official docs do not explain how passages are segmented or ranked.
Case 2: Pulling full-page text for topic analysis. Scenario: when passages are not enough and you need fuller context, call rag_search_ddgs, which officially returns full pages as text — the project's original mode. Note that a single call returns at most 40,000 characters, adjustable with the MCPSURFR_MAX_CHARS environment variable. The exact parameters of each tool are not documented item by item; trust the tool descriptions your client introspects. How the deep_research series orchestrates multi-step research is not elaborated on the official page — do not assume a workflow on your own.
Limits of Use
Read/write nature: all six tools are query or research capabilities; the official page describes no operations that write local files or submit to remote endpoints. This is a boundary description, not a security conclusion — every call triggers a real web search and re-ranks results locally with MobileBERT (numpy).
Credentials and local dependencies: the official pitch is that no API keys are needed. Whether an account, tokens, or local data files are required is not mentioned on the official page; treat it as unconfirmed.
Side effects and confirmation points: installation pulls and runs code from GitHub via uvx, which is inherent to the official configuration — accept this before writing the config. Beyond that, the official docs describe no other side effects or actions requiring confirmation.
Official limits and unconfirmed items: full-page tools return at most 40,000 characters per call, adjustable with the MCPSURFR_MAX_CHARS environment variable. Other key information not yet confirmed includes: the list of supported clients, the availability and quotas of each search backend, performance overhead, and whether remote deployment is possible. Before making a choice that depends on any of these, verify them in your own environment.