mcpsurfr

MCP を通じて、LLM 向けのローカルウェブ検索を提供します。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 バナー、フッターは含まれません。コードブロックと表の行は保持されます。同じページが 2 つの URL にある場合も、結果は 1 件だけです。
• ページではなく文章を返します。 search は質問への回答となる段落だけを返すため、トークン数は約 10 分の 1 です。適切な一致が見つからない場合は、代わりにページ全体を取得するかどうかを尋ねます。
• 省略した内容を通知します。 結果には、スキップしたページとその理由（ブロック、PDF、重複など）が表示されます。途中で切り詰めたページには truncated と表示され、フォールバックやエンジンのエラーは warnings に表示されます。Google は頻繁にブロックするため、自動的に auto にフォールバックします。
• 使い方ガイドを内蔵。 スキルと 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"]
    }
  }
}

ページ全体を返すツールは、1 回の呼び出しにつき 40k 文字（約 10k トークン）の上限を共有します。変更するには、サーバーのエントリーに "env": {"MCPSURFR_MAX_CHARS": "80000"} を追加します。

設定ファイルの場所がわからない場合は、MCP クイックスタートを参照してください。Claude Desktop、Claude Code、Cursor、Goose でテスト済みです。

mcp-local-rag から移行する場合：以前の URL はリダイレクトされ、mcp-local-rag コマンドも引き続き利用できるため、古い設定のまま動作します。上記の設定に切り替えると新しい名称が使われ、--python=3.10 の固定指定がなくなります（3.10 は今月サポート終了を迎えます）。

スキルとプロンプト

mcpsurfr-search スキルは、使用するツールとバックエンドの選び方、および引用方法をモデルに伝えます。サーバーはこれを skill://mcpsurfr-search/SKILL.md として提供するため、ほとんどのクライアントでは追加設定は不要です。Claude Desktop に手動で追加するには、Settings → Skills → Add from folder を選択し、src/mcpsurfr/skills/mcpsurfr-search/ を指定します。

research(topic) プロンプトは、いくつかの検索語を計画し、deep_research を実行して、出典を引用した要約を作成します。

例

Claude Desktop に、学習データより新しい情報について質問する例：

---

MseeP によるセキュリティ監査 · 課題やプルリクエストを歓迎します · MIT ライセンス · お役に立った場合はコーヒーをごちそうしてください