free-search-mcp

👁 License
👁 Python
👁 MCP

ローカルファーストかつAPIキー不要のModel Context Protocolサーバーです。あらゆるLLM（Claude、GPT、ローカルのOllamaなど）に対して、検索APIの登録なしで、ウェブ検索、ページの取得とクリーンアップ、ドキュメントの読み取り機能を提供します。

既存のオープンソースMCPの優れたアイデアを1つのPythonパッケージにまとめ、それぞれに欠けていたLLM向けの使いやすさと信頼性を向上させました。

research("how does reciprocal rank fusion work", depth=3)
 ↓
# Research brief: how does reciprocal rank fusion work
_engines: duckduckgo, mojeek, startpage · sources: 3 · ~3,400 tokens_

## Sources
- [1] Reciprocal rank fusion | Elasticsearch Reference — <https://…>
- [2] Hybrid Search Scoring (RRF) | Microsoft Learn — <https://…>
- [3] RRF explained in 4 mins — Medium — <https://…>

## Documents
…full Markdown bodies of each page, ready for the LLM to read…

1回のツール呼び出し。3つのソース。APIキー不要。検索のためのOPENAI_API_KEYのような面倒な手続きもありません。

なぜこれが必要なのか

既存の検索MCPはそれぞれ特定の機能に優れていますが、通常はそのすべてを必要とします：

ここで「LLM調整済み」とは、Markdown優先の出力、トークン見積もり、段落境界でのスマートな切り詰め、モデルが適切なツールを選択するための「Best for / Not for / Returns / Common mistakes」ドキュメント文字列、実用的なエラーヒント、MCPプロンプトとリソーステンプレート、そして検索→取得→取得→取得を1ターンにまとめるワンショットのresearch()機能を指します。

「Trafilatura」とは、trafilaturaを使用してメインコンテンツを抽出することを意味します。これはBevendorff 2023 ROUGEベンチマークで勝者となったツールです（単純なボイラープレート除去の約0.55に対し、約0.85）。取得した各ページは、author、published_date、sitenameも無料で返します。

「フィルタ」とは、検索/リサーチがfreshness、include_domains、exclude_domains、category (news/pdf/github/paper/forum/blog)、include_text、exclude_textを受け入れることを意味します。

Related MCP server: TOOL4LM

ツール

さらに、2つのMCPプロンプト（Research thoroughly、Fact-check claim）と、再取得せずにキャッシュされたページをコンテキストに戻すためのリソーステンプレート（cache://page/{url}）が含まれています。

フィルタ (search / research)

すべてのツールはデフォルトでformat="markdown"を使用します。これは読みやすく、JSONよりもトークン数が約40%少なく、出所とトークン予算ヘッダーが含まれます。構造化されたアクセスが必要な場合はformat="json"を渡してください。

ツールのアノテーション

すべてのツールには、MCPクライアントがそれらにラベルを付け、高度なアクションを制御できるように、正しいreadOnlyHint、idempotentHint、openWorldHintアノテーションが付属しています。

エンジン

デフォルトセット（すべて信頼性が高く、繰り返し呼び出してもCAPTCHAが発生しない）： duckduckgo、mojeek、startpage。

オプトイン（ヘッドレスクライアントに対して断続的にチャレンジが発生する）： brave、bing、baidu。

Brave/Bing/Baiduは、数回呼び出すとヘッドレスブラウザをブロックします（PoW CAPTCHA、「something went wrong」ページ、リダイレクトラッパーなど）。デフォルトで必要な情報が見つからない場合にのみ、engines=["brave"]などを渡してください。

インストール

git clone https://github.com/ymylive/free-search-mcp.git
cd free-search-mcp
uv sync
uv run playwright install chromium

スタンドアロンサーバーとして実行（stdioトランスポート）：

uv run search-mcp

ライブテストを実行（実際のウェブにアクセスします。環境変数を設定してください）：

SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v

オフラインテストはデフォルトで実行され、ネットワークにはアクセスしません。

Claude Desktopへの組み込み

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）またはお使いのプラットフォームの同等のファイルに以下を追加します：

{
 "mcpServers": {
 "search": {
 "command": "uv",
 "args": ["--directory", "/absolute/path/to/free-search-mcp", "run", "search-mcp"]
 }
 }
}

Claude Desktopを再起動します。上記の7つのツールがツールドロワーに表示されます。

他のクライアントへの組み込み

このサーバーはstdio経由で標準のMCPを話します。MCPをサポートするものであれば何でも動作します：

• Claude Code (claude mcp add search uv --directory /…/free-search-mcp run search-mcp)

• Cursor / Continue / Cline (上記のJSONスニペットを使用)

• 公式MCP SDKを使用したカスタムPython / TypeScriptクライアント

設定

すべての設定は、SEARCH_MCP_で始まる環境変数で上書きできます：

アーキテクチャ

 ┌─────────────────────────────────────────────────────┐
 │ FastMCP server (stdio) │
 │ tools: search / research / fetch / fetch_batch / │
 │ read_doc / cache_search / engines │
 └────────────┬────────────────────────────────────────┘
 │
 ┌────────────▼────────────┐ ┌────────────────────────┐
 │ aggregator │ │ fetcher │
 │ - parallel engines │ │ - httpx fast path │
 │ - reciprocal rank │ │ - playwright fallback │
 │ fusion │ │ - markdownify │
 │ - search cache (FTS5) │ │ - page cache (FTS5) │
 └────┬────────────────────┘ └────────────┬───────────┘
 │ │
 ┌────▼─────────────────┐ ┌──────────────▼─────────────┐
 │ engines/ │ │ browser pool │
 │ duckduckgo.py │ │ - persistent context │
 │ mojeek.py │ │ - stealth init script │
 │ startpage.py │ │ - shared cookies │
 │ brave.py (opt) │ │ - semaphore-bounded pages│
 │ bing.py (opt) │ └────────────────────────────┘
 │ baidu.py (opt) │
 └──────────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ documents/ │ │ ratelimit │
 │ pypdf, python-docx, │ │ token bucket │
 │ markdownify │ │ per engine │
 └────────────────────────────┘ └──────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ formatting │ │ research │
 │ token estimate │ │ composed │
 │ smart truncation │ │ workflow │
 │ markdown renderers │ │ │
 └────────────────────────────┘ └──────────────────┘

エンジンアダプターパターン

src/search_mcp/engines/内の各エンジンは以下を実装しています：

class Engine:
 name: str
 needs_browser: bool # Force Playwright?
 wait_selector: str | None # CSS to wait for in browser mode

 def build_url(self, query: str, max_results: int) -> str: ...
 def parse(self, html: str) -> list[SearchResult]: ...

基底クラスは、トランスポート（httpx → Playwrightフォールバック）、レート制限、およびHTTPが結果の代わりにCAPTCHAシェルを返す場合（ブラウザ経由で自動再試行）を処理します。

クレジット

このプロジェクトは以下の成果の上に成り立っています：

• mrkrsl/web-search-mcp — スマートなhttpxからPlaywrightへのフェッチ戦略、マルチエンジンフォールバックチェーン

• Aas-ee/open-webSearch — マルチエンジンの広範性 (Bing/DDG/Baidu/Brave/Startpage)

• VincentKaufmann/noapi-google-search-mcp — 検知回避パターン (navigator.webdriver, UA, cookies)、SQLite FTS5キャッシュのアイデア、マルチフォーマットのread_document

• nickclyde/duckduckgo-mcp-server — エンジンごとのレート制限、LLMフレンドリーなコンテンツクリーンアップ

• Mojeek — User-Agentで制限をかけない独立した検索インデックス

• Model Context Protocol および 公式Python SDK

ライセンス

MIT — LICENSEを参照してください。

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• cache_searchA
• compareA
• enginesA
• extract_structuredA
• fetchA
• fetch_batchA
• read_docA
• researchA