mcpsurfr

通过 MCP 为你的大模型提供本地网页搜索。无需 API 密钥，搜索结果在你的设备上排序。原名 mcp-local-rag。

%%{init: {'theme': 'base'}}%%
flowchart TD
    A[LLM] -->|query| S["Search with ddgs (auto: several engines, no keys)"]
    S -->|"rag_search, deep_research"| R["Re-rank results locally (MobileBERT on numpy)"]
    R --> P[Fetch top pages, keep the main content]
    P -->|page text + URLs| A
    S -->|search| T1["Tier 1: pick pages by their snippets"]
    T1 --> T2["Tier 2: split into passages, keyword match (BM25)"]
    T2 -->|few hits| OUT["Best passages + URLs (about 800 tokens)"]
    T2 -->|too many or none| T3[Tier 3: rank them by meaning]
    T3 --> OUT
    OUT --> A

功能一览：

• 无需 API 密钥。 通过 ddgs 搜索。其 auto 模式会同时查询多个引擎，并跳过受阻的引擎。
• 本地排序。 使用基于纯 numpy 的小型 MobileBERT 模型对结果重新排序，因此只会抓取最相关的页面。
• 纯净文本。 抓取页面时会模拟浏览器，只保留主要内容：不包含菜单、Cookie 横幅或页脚。代码块和表格会保留原有行结构。同一页面即使对应两个 URL，也只会返回一次。
• 返回段落而非页面。 search 只返回能回答问题的段落，约为页面全文的十分之一 token 数。如果匹配结果不理想，还可以询问你是否需要完整页面。
• 说明省略内容。 结果会列出跳过的页面及原因（受阻、PDF、重复等）；被截断的页面会标记为 truncated，回退情况和引擎故障则会显示为 warnings。Google 经常会阻止请求，因此工具会自动回退到 auto。
• 自带使用指南。 服务会提供一项 skill 和一个 research 提示词，让客户端无需额外设置就能了解如何使用。

工具	用途
search	从这里开始：仅返回相关段落。传入 keywords 可获得更好的结果
rag_search_ddgs	以文本形式返回完整页面（原始模式）
rag_search_google	同上，通过 Google 搜索（受阻时回退到 auto）
deep_research	使用多个搜索词跨后端搜索，并合并去重
deep_research_ddgs / deep_research_google	deep_research 的快捷方式

后端：auto（默认）、brave、duckduckgo、google、grokipedia、mojeek、startpage、wikipedia、yahoo。auto 和 brave 是较可靠的选项。

安装

使用 uv：

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

也可以使用 Docker（amd64 和 arm64）：

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

完整页面工具的每次调用共享 40k 个字符的额度（约 10k 个 token）。要更改此值，请在服务条目中添加 "env": {"MCPSURFR_MAX_CHARS": "80000"}。

不确定配置文件在哪里？请参阅 MCP 快速入门。已在 Claude Desktop、Claude Code、Cursor 和 Goose 上测试。

从 mcp-local-rag 迁移？ 旧配置仍可继续使用，因为旧 URL 会重定向，mcp-local-rag 命令也仍然存在。改用上面的配置即可采用新名称，并移除 --python=3.10 版本锁定（3.10 将于本月结束生命周期）。

Skill 和提示词

mcpsurfr-search skill 会告诉模型该选择哪个工具和后端，以及如何引用来源。服务会通过 skill://mcpsurfr-search/SKILL.md 提供它，因此大多数客户端无需额外配置。要手动将其添加到 Claude Desktop：Settings → Skills → Add from folder，然后选择 src/mcpsurfr/skills/mcpsurfr-search/。

research(topic) 提示词会规划几个搜索词、运行 deep_research，并撰写带引用的摘要。

示例

向 Claude Desktop 询问训练数据中没有的新近信息：

---

MseeP 安全审计 · 欢迎提交问题和 PR · MIT 许可 · 如果它对你有帮助，请请我喝杯咖啡