Free Search

free-search-mcp

https://github.com/user-attachments/assets/354b522a-ef6b-4547-bb07-c80c6268a5e8

_{音楽：「Ethereal Space (cdk Mix)」by cdk、ccmixter.org/files/cdk/34151、CC BY 3.0のライセンスに基づいています。}

free-search-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, bing, anysearch · 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回だけです。API キーを使わずに、全文を含む3つの情報源が返されました。

クイックスタート

必要なのは uv だけです。登録も、API キーも、クローンも必要ありません。

Claude Code のセッション内で：

/plugin marketplace add sweetcornna/free-search-mcp
/plugin install free-search@free-search-mcp

Codex では：

codex plugin marketplace add sweetcornna/free-search-mcp
codex plugin add free-search@free-search-mcp

（Codex では、以前の codex mcp add によって ~/.codex/config.toml に残された [mcp_servers.search] エントリーが、プラグインのサーバーを暗黙に優先します。codex mcp remove search で削除してください。）

プラグインには、11個のツール、verified-research スキル（スニペットとそのページおよび日付を照合する方法）、さらに Claude Code では free-search:quick-search エージェントが含まれており、すべて同じバージョンに固定されています。 /plugin update free-search を実行すると、次のリリースに更新されます。

任意で、ブラウザー描画が必要な検索エンジン（brave、startpage、zhihu など）や JavaScript を多用するページのために、Chromium を一度インストールしてください。それ以外の機能は Chromium なしで動作します。Chromium が必要な呼び出しでは、エラーとして次のコマンドが返されます。

uvx --from free-search-mcp playwright install chromium

Claude Desktop、その他のクライアント、ソースのチェックアウト、Docker については、インストールをご覧ください。

このプロジェクトを作った理由

	複数エンジン	API キー不要	スマートなフォールバック	PDF/DOCX	FTS5 キャッシュ	フィルター	Trafilatura	LLM 向け最適化
nickclyde/duckduckgo-mcp-server	✗	✓	✗	✗	✗	✗	✗	~
mrkrsl/web-search-mcp	✓	✓	✓	✗	✗	✗	✗	~
Aas-ee/open-webSearch	✓	✓	~	✗	✗	✗	✗	~
VincentKaufmann/noapi-google-search-mcp	✗	✓	✓	✓	✓	✗	✗	~
free-search-mcp	✓	✓	✓	✓	✓	✓	✓	✓

「LLM 向け最適化」とは、Markdown を優先した出力、トークン数の推定、次の手順を示すエラー、そして検索と取得を1回の呼び出しにまとめる research() を意味します。わかりにくい列については、docs/HOW_IT_WORKS.mdで説明しています。

ツール（11）

ツール	説明
search(query, ...filters)	複数の検索エンジンで並列検索し、RRF で統合します。タイトルのあいまい一致とホストの正規化に基づいて重複を除去し、抽出的な lead_snippet を任意で含められます
research(question, depth?, ...filters)	1 回の操作で、検索して上位 N 件を取得し、Markdown の概要を返します
paper_graph(paper, direction?, limit?)	論文 1 件の引用グラフをたどります。参考文献、影響力順に並べた引用文献、Crossref の撤回・訂正通知を取得します。DOI、OpenAlex ID、正確なタイトル、または arXiv の参照（arXiv:1706.03762、arxiv.org/abs/… URL、10.48550/arXiv.… DOI、あるいは入力全体が 1706.03762、2401.12345v3、hep-th/9901001 のような ID）を指定します
compare(question, urls=[2..5])	2～5 件の URL を並列取得し、質問を軸にした抜粋を並べて表示します
fetch(url, render?, inline?, ...)	任意のリソースを取得します。ページはリーダーモードの Markdown、ドキュメントは解析済みテキスト、画像やバイナリは説明（種類／サイズ／寸法／sha256）を返します。inline=True を指定すると、画像自体をビジョンモデルに返します
fetch_batch(urls, ...)	複数の URL を並列取得します（1 回の呼び出しにつき最大 20 件）
read_doc(source, start?, length?, ...)	ページネーションに対応して、PDF／DOCX／XLSX／PPTX／EPUB／CSV／コード／zip-tar／HTML／TXT／MD を解析します
extract_structured(url, ...)	extruct で JSON-LD／OpenGraph／Twitter カード／マイクロデータを取得します。長い散文フィールド（articleBody など）は切り詰められ、その旨が trimmed に記載されます。このツールが返すのはメタデータです。テキストには fetch を使用してください
cache_search(query, limit?, ...)	以前に取得したページを対象に FTS5 で検索します
engines(group?)	ソースツリーを（グループ、サブグループ、エンジンの順に）1 行ずつ表示します。group はエンジンを所有するグループの列挙値であり、誤記があるとスキーマ検証に失敗します
download(url, ...)	デフォルトでは ${SEARCH_MCP_CACHE_DIR}/downloads にファイルを保存します。ファイルは 24 時間後に自動削除されます。無効にするには SEARCH_MCP_DOWNLOAD_ENABLED=false を設定します。

5 つの MCP プロンプトと 2 つのリソーステンプレート（cache://page/{url}、 cache://search/{query_hash}）もあります。12 番目のツールである ask は、 回答バックエンドが設定されている場合にのみ表示されます（検索の委任を参照）。

search と research では、次のフィルターを指定できます。

パラメーター	値	効果
freshness	day / week / month / year	過去 N 日／週／月／年の結果のみを対象にします。日付のない結果は保持され、その大半を占める場合は freshness_note に記載されます。day / week では googlenews も追加されます
include_domains	["python.org", "djangoproject.com"]	指定したドメインに限定します
exclude_domains	["pinterest.com"]	指定したドメインを除外します
category	グループ（paper、finance、news、software、security、weather、…）またはサブグループ（paper.biomed、finance.filings、finance.fx、software.python、dataset.ml、…）	該当する種類の情報をネイティブにインデックス化するソースに振り分けます。ツールスキーマの列挙値に、すべての値が記載されています
include_text	"async"	タイトル／スニペットに必須の部分文字列を指定します
exclude_text	"beginner"	タイトル／スニペットに含めない部分文字列を指定します
max_age_hours	24	この時間数より新しい場合に限り、キャッシュされた回答を受け入れます。デフォルトは 7 日です。この値、freshness ウィンドウの TTL、6 時間のニュース上限、カテゴリ固有の上限（weather、finance.fx は 1 時間、software、security は 6 時間）のうち、最も短いものが適用されます

デフォルトでは、出典情報とトークン推定値をヘッダーに含む Markdown が出力されます。 format="json" を指定すると、構造化データが返されます。

検索の実行方法

• エンジンを指定しない検索では、キー不要の小規模なプールである duckduckgo、 bing、anysearch、mojeek に問い合わせます。最新情報が求められる場合は googlenews が加わり、クエリが中国語で書かれている場合は so360 が加わります。
• category= を指定すると、その種類の情報（論文、 企業提出書類、データセット、パッケージ、CVE など）をインデックス化するソースに振り分けられます。pypi、nvd、 openmeteo などのレコードソースも、質問に直接回答できる場合は自動的に加わります。
• CAPTCHA、ログイン画面、または無関係なページを返すエンジンは一時的に外され、代わりのエンジンが使われ、何が起きたかがレスポンスに示されます。IP による制限への対処には、プロキシ（SEARCH_MCP_PROXY）を使います。
• すべての結果には、どれくらい古い情報か、その日付の出典が示されるため、エージェントは手がかりと確認済みの事実を見分けられます。
• engines() はソースツリー全体を表示します。engines=["so360", "baidu"] を指定すると、名前を指定したエンジンだけが実行されます。

検索から自動的に呼び出されるエンジンにキーは必要ありません。測定結果を含む詳細はdocs/HOW_IT_WORKS.md、制限やプロキシについてはdocs/PROXY_AND_GATES.md、ツールの使用例を交えた紹介はdocs/USAGE.mdをご覧ください。

インストール

クイックスタートのプラグインを推奨します。サーバーのバージョンがプラグインのバージョンに固定され、プラグインと一緒に更新されるためです。それ以外の方法でも、同じサーバーを実行できます。

場所	方法
Claude Desktop	最新リリースから free-search-mcp-<version>.mcpb を開きます
MCP Registry	io.github.sweetcornna/free-search-mcp
Claude Code、プラグインなし	claude mcp add search -s user -- uvx free-search-mcp
Codex、プラグインなし	codex mcp add search -- uvx free-search-mcp
Hermes Agent（プラグイン）	hermes plugins install sweetcornna/free-search-mcp/plugins/free-search --enable
その他の MCP クライアント	stdio コマンド uvx free-search-mcp
Docker	docker compose build を実行し、その後 docker compose run --rm search-mcp を実行します

Chromium、スモークテスト、クライアント登録を一度に行う、ソースコードのチェックアウト方法：

curl -LsSf https://raw.githubusercontent.com/sweetcornna/free-search-mcp/main/scripts/install.sh | bash -s -- --client claude-code

HTTP 経由では、uvx free-search-mcp --transport streamable-http --port 8000 を実行すると、http://127.0.0.1:8000/mcp でサービスを提供します。このエンドポイントには認証がなく、アクセスしたユーザーに対して任意の URL を取得するため、ループバックに限定するか、認証プロキシを前段に配置してください。

Claude Desktop、Cursor、Cline、Continue、Zed 用の JSON、インストーラーのオプション、プラグインのトークンコストについてはdocs/INSTALL.mdをご覧ください。エージェントの運用ルールについてはdocs/AGENT_USAGE.mdをご覧ください。

自分のアカウントで検索：codex と antigravity

サインインしたアカウントを使って検索する、オプトイン方式のエンジンが 2 つあります。API キーは不要です。どちらもプールや振り分け先には含まれず、呼び出しで名前を指定した場合にのみ検索に使われます。サインインしないユーザーには何の変更もありません。

	codex	antigravity
検索に使用	OpenAI のウェブ検索。Codex が使用するものです	Gemini モデルによる Google Search
アカウント	Codex が含まれる ChatGPT プラン	Antigravity を利用できる Google アカウント
各検索で使用されるもの	プランの Codex 利用枠	アカウントの Antigravity 利用枠
プロバイダーによる利用許可	はい	いいえ。以下の警告をご覧ください
サインインページが自動的に開く	初回使用時。デスクトップで stdio 経由の場合	いいえ
詳細ガイド、中文速览付き	docs/CODEX_SEARCH.md	docs/ANTIGRAVITY_SEARCH.md

警告：Google の Antigravity 利用規約では、サードパーティ製ツールからのサインインの使用が禁止されており、その結果として Antigravity と Gemini CLI のアカウントが停止される可能性が明記されています。実際に Google は、この理由でアカウントを停止しています。こうしたリスクを受け入れられるアカウントでのみ、antigravity にサインインしてください。

1. 一度だけサインインする

サーバーを実行するマシンでサインインを実行します。

uvx --from free-search-mcp search-mcp-login codex         # the ChatGPT page `codex login` shows
uvx --from free-search-mcp search-mcp-login antigravity   # prints the warning, then Google's consent page
uvx --from free-search-mcp search-mcp-login status        # account, plan, token expiry

（ソースをチェックアウトした場合は、uv run search-mcp-login … を実行します。）設定ページの search-mcp-admin にも、同じ［Sign in］／［登录］ボタンがあります。トークンは ~/.config/search-mcp/oauth/（0600）に保存され、自動的に更新されます。プラグイン、 uvx、デスクトップ版のバンドルはすべてこのディレクトリを読み取るため、実行中のサーバーは 再起動せずに新しいサインインを認識します。

• codex はこの手順を省略できます。名前を指定した最初の検索でサインインページが開き、承認すると サインインが完了します（デスクトップでの stdio の場合のみです。 SEARCH_MCP_CODEX_AUTO_SIGNIN=false にすると無効になります）。すでに Codex CLI にサインインしているマシンでは、そのサインイン情報を読み取り専用で再利用できます。 search-mcp-login codex --use-codex-cli を実行してください。
• antigravity は Antigravity 独自の OAuth クライアントでサインインします。このクライアントは このパッケージに同梱されていません。サインイン時に、マシンにインストールされた Antigravity アプリから 読み取ります（macOS で確認済みです）。Antigravity がインストールされていない場合は、 SEARCH_MCP_ANTIGRAVITY_CLIENT_ID と SEARCH_MCP_ANTIGRAVITY_CLIENT_SECRET を設定してください。サインイン済みのマシンでは、 どちらも ~/.config/search-mcp/oauth/antigravity.json に保存されます。

2. エンジンを指定する

search("rust 2024 edition changes", engines=["codex"])
research("what changed in python 3.14 asyncio", engines=["antigravity"])
search("rust 2024 edition changes", engines=["codex", "duckduckgo", "bing"])

Claude Code または Codex では、「codex エンジンで検索して」のように言葉で指定してください。 フィルターは通常どおり適用され、結果はほかの検索と同様にキャッシュされます。2026-09-26 の 測定では、codex の検索には約 3 秒、antigravity の検索には 10〜20 秒かかりました。

3. 設定（すべて省略可能）

変数	デフォルト	意味
SEARCH_MCP_CODEX_MODEL、SEARCH_MCP_ANTIGRAVITY_MODEL	latest	latest はアカウントのモデルカタログに追従するため、新しいモデルが掲載されると使用されます。モデル名を指定すると、そのモデルに固定されます
SEARCH_MCP_CODEX_TIMEOUT、SEARCH_MCP_ANTIGRAVITY_TIMEOUT	60	1 回の検索にかける秒数
SEARCH_MCP_CODEX_AUTO_SIGNIN	true	初回使用時にサインインページを開きます
SEARCH_MCP_ANTIGRAVITY_CLIENT_ID、SEARCH_MCP_ANTIGRAVITY_CLIENT_SECRET	Antigravity のインストール先から読み取り	Antigravity がないマシン向けです。両方を設定するか、どちらも設定しないでください
SEARCH_MCP_PROXY	空	サインインと検索にこのプロキシを使用します

サーバー、SSH 経由、または Docker での使用

• --no-browser を指定してサインインします（search-mcp-login codex --no-browser または antigravity --no-browser）。表示されたアドレスを任意のブラウザーで開き、承認してください。 その後、ブラウザーで 127.0.0.1:1455 または localhost:51121 のアドレスを読み込めずに 失敗するため、そのアドレス全体をターミナルに貼り付けます。
• streamable-http 経由の場合、codex はサインインページを自動で開きません。サーバー上で ページが開いてしまうためです。先に上記のコマンドでサインインしてください。
• Docker では、トークンがコンテナの終了後も残るように、SEARCH_MCP_CONFIG_DIR を マウントしたボリュームに設定し、コンテナ内で --no-browser を指定してサインインしてください。 Docker で antigravity を使うには、2 つのクライアント変数も必要です。

search-mcp-login logout codex または logout antigravity を実行すると、保存された トークンが削除されます。Antigravity 自体へのアクセスを取り消すには、Google アカウントの ［サードパーティ製アプリとサービス］から削除してください。

動作しない場合

エラーの内容	対処方法
codex not configured ／ antigravity not configured	このマシンにサインイン情報が保存されていません。上記の手順でサインインしてください
port 1455 and 1457 … are in use、または port 51121	別のサインイン（codex login や、開いたままのサインインページ）がポートを使用しています。閉じてから再試行してください
使用制限、クォータ、またはレート制限に達した	エラーに表示されたリセット時刻まで待ってください。キー不要のエンジンは引き続き使えます
needs Antigravity's OAuth client	Antigravity をインストールするか、2 つのクライアント変数を設定してください
antigravity の HTTP 403 no valid license	SEARCH_MCP_ANTIGRAVITY_VERSION に、インストールされている Antigravity のリリースを設定してください。Google がアカウントを制限している場合にも、このエラーが表示されることがあります
has expired or was revoked	もう一度サインインしてください

任意：独自の API キー

API キーは必要ありません。また、エージェントが API キーを尋ねることはありません。6 つのエンジンは、呼び出しで指定され、かつ運用者が独自のキーを設定している場合にのみ実行されます。

エンジン	プロバイダー	キー
brave_api	Brave Search API	SEARCH_MCP_BRAVE_API_KEY
serper	Serper	SEARCH_MCP_SERPER_API_KEY
serpbase	SerpBase	SEARCH_MCP_SERPBASE_API_KEY
tavily	Tavily	SEARCH_MCP_TAVILY_API_KEY
google_cse	Google Custom Search	SEARCH_MCP_GOOGLE_CSE_API_KEY + SEARCH_MCP_GOOGLE_CSE_CX
github_code	GitHub	SEARCH_MCP_GITHUB_TOKEN

環境変数または .env の行としてキーを設定するか、ローカルの設定ページで設定してください。

uv run search-mcp-admin        # local settings / 本地设置 — http://127.0.0.1:8765

（プラグインまたは uvx インストールの場合は uvx --from free-search-mcp search-mcp-admin を実行します。） このページはバイリンガル（中英双语）で、127.0.0.1 のみにバインドし、保存したキーを再起動なしで適用します。また、保存済みの値を再表示することはありません。プロバイダーごとの手順は docs/API_KEYS.md をご覧ください。

検索を委任する

委任すると、呼び出し元のコンテキストにページのテキストを含めずに、日付付きの情報源と簡潔な回答を返せます。これらの機能は、デフォルトではどれも有効になっていません。

要望	使用するもの	必要なもの
エージェント自身に検索と読み取りをさせる	インストール済みのツール	なし
ホスト独自のサブエージェントに検索させる	quick-search エージェント定義	サブエージェントに対応したホスト
サーバーから Claude Code 経由で実行する	SEARCH_MCP_AGENT_BACKEND=claude-code	ログイン済みの claude CLI
サーバーから Codex 経由で実行する	SEARCH_MCP_AGENT_BACKEND=codex	ログイン済みの codex CLI
選択したモデルエンドポイントをサーバーから呼び出す	SEARCH_MCP_AGENT_BACKEND=api	OpenAI 互換または Anthropic 互換の URL
独自のコードからモデルを指定する	Python での ask(question, answer_with=...)	ほかには何も必要ありません

設定、エージェントファイル、計測済みの実行時間については、 docs/DELEGATION.md をご覧ください。

設定

設定は不要です。設定値は SEARCH_MCP_* 変数で指定し、まず環境変数、次に ./.env、最後に ~/.config/search-mcp/.env から読み込まれます（SEARCH_MCP_CONFIG_DIR でこのディレクトリを変更できます）。よく変更される設定は次のとおりです。

変数	デフォルト	説明
SEARCH_MCP_PROXY	空	エンジン、ブラウザー、fetch で使用する送信プロキシ（http、https、socks5）
SEARCH_MCP_PROXY_ENGINES	空	指定したエンジンのみプロキシを使用
SEARCH_MCP_DEFAULT_ENGINES	["duckduckgo","bing","anysearch","mojeek"]	エンジンを指定せずに検索するときに使用するエンジン群
SEARCH_MCP_REGION	us-en	ロケール指定を受け付けるエンジンのロケール
SEARCH_MCP_CACHE_DIR	~/.cache/search-mcp	検索とページのキャッシュ
SEARCH_MCP_TOOLS	空	指定したツールのみ登録

すべての設定は docs/CONFIGURATION.md に記載され、.env.example で説明されています。

開発

git clone https://github.com/sweetcornna/free-search-mcp.git && cd free-search-mcp
uv sync && uv run playwright install chromium
uv run pytest -q                              # offline
SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v    # live, hits the real web

チェックアウト内で claude を実行すると、リポジトリの .mcp.json が読み込まれ、作業ツリーのサーバーが起動します。アーキテクチャについては docs/HOW_IT_WORKS.md を、リリースの作成については docs/RELEASING.md をご覧ください。

クレジット

このプロジェクトは、以下を基盤としています。

• mrkrsl/web-search-mcp：httpx の後に Playwright を使用するフェッチ戦略と、複数の検索エンジンを使ったフォールバックチェーン
• Aas-ee/open-webSearch： 複数の検索エンジンへの対応（Bing/DDG/Baidu/Brave/Startpage）
• VincentKaufmann/noapi-google-search-mcp： 検出回避のパターン（navigator.webdriver、UA、Cookie）、SQLite FTS5 キャッシュのアイデア、複数形式に対応した read_document
• nickclyde/duckduckgo-mcp-server： 検索エンジンごとのレート制限と、LLM 向けのコンテンツ整理
• Mojeek：User-Agent で制限しない独立系の検索インデックス
• Model Context Protocol と 公式 Python SDK

ライセンス

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