Web Research MCP

AIエージェント向けの高品質・マルチソースなWebリサーチMCPサーバー。Claude Desktop、Hermes、Cursor、またはMCP互換の任意のクライアントに接続して、Wikipedia、arXiv、Hacker News、Stack Exchange、Crossref、Brave、Tavily、そしてWeb上の任意のURLにわたる本番グレードの検索＋ページ取得を利用できます。

# One-line install (anywhere on disk)
git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research --command "$(pwd)/web-research-mcp/bin/web-research-mcp"
# 6 of 7 tools work with zero API keys. Add Brave or Tavily to unlock general web search.

なぜこれを作ったのか

ほとんどの「Web検索」MCPサーバーは、ランダム化されたフィンガープリントを持つヘッドレスブラウザでGoogleをスクレイピングしようとします。そのアプローチは負け戦です。検索エンジンは数日以内にスクレイパーを検出して禁止しますし、たとえ機能したとしても、LLMが後処理しなければならないDOMのスープが得られるだけです。

このサーバーは別のアプローチを取ります — エージェント向けに作られたAPIと通信します:

7つのソースはすべてAPIキーなしで動作します。BraveまたはTavilyのキーを追加すると、リアルタイムの一般Web検索が利用可能になります。これが最高品質のアプローチです。実際のWebインデックスAPIは、スクレイパーが再現できないシグナル（クリックモデル、新しさ、リンク分析）を使用するため、スクレイピングよりも優れた結果が得られます。

クイックスタート

オプションA — pip install（公開時）

pip install web-research-mcp
hermes mcp add web-research --command "$(which web-research-mcp)"

オプションB — ソースからクローン

git clone https://github.com/infinit3labs/web-research-mcp.git
hermes mcp add web-research \
  --command "$(pwd)/bin/web-research-mcp"

プロンプトが表示されたら、7つのツールすべてを受け入れます。完了です。

オプションC — Claude Desktopでインストール

~/Library/Application Support/Claude/claude_desktop_config.jsonを編集:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/code/mcp-servers/web-research/bin/web-research-mcp"
    }
  }
}

オプションD — Cursor / 任意のstdio MCPクライアントでインストール

{
  "mcpServers": {
    "web-research": {
      "command": "/absolute/path/to/web-research-mcp/bin/web-research-mcp"
    }
  }
}

ランチャースクリプトは初回実行時にvenvを自動作成し、pyproject.tomlから依存関係をインストールし、設定済みのAPIキーをweb-research.envから読み込みます。

2.（任意）実際のWeb検索用のAPIキーを追加

cp web-research.env.example web-research.env
$EDITOR web-research.env

ランチャーは呼び出しのたびにweb-research.envからキーを読み込みます。MCPクライアントの再起動は不要です。

3. 使ってみる

エージェントに次のようなことを依頼してみてください:

「Hacker NewsとStack Overflowで2026年にリリースされた最高のMCPサーバーを検索して」

「pro_modeを使って小規模言語モデルの現状をリサーチして」

「https://arxiv.org/abs/2506.06962 を取得して方法論を要約して」

「この主張をWikipediaとarXivで相互参照して」

ツール

tools/listに登録されている7つのツールすべて:

search_web — マルチソースの一般Web検索

search_web(
    query: str,                  # search query
    max_results: int = 10,       # per source, before dedup (1–30)
    pro_mode: bool = False,      # also fetch top 3 URLs and append excerpts
) -> str

Brave + Tavilyをバックエンドとし、URL正規化による重複排除とクロスソースのスコアブースティングを備えています。BRAVE_API_KEYおよび/またはTAVILY_API_KEYが必要です。キーがない場合は、有効化方法を説明する明確なメッセージを返します。

pro_mode: trueはリサーチの切り札機能です。通常の検索を実行し、上位3件の結果をJina経由で取得して、そのコンテンツをスニペットとして追加します。1回の呼び出しで、通常ならsearch_web＋3回のfetch_urlが必要な処理を実行できます。

fetch_url — 任意のページのクリーンなMarkdown

fetch_url(url: str) -> str

Jina Readerを経由します。Jina Readerは:

• JS多用のページ（SPA、Reactアプリ）をレンダリング

• ほとんどのボット検出を回避（Jinaはホワイトリスト登録済み）

• メタデータブロック（Title:、URL Source:、Published Time:）付きのクリーンなMarkdownを返す

• コンテキストウィンドウを保護するため約2万文字に切り詰める

search_wikipedia — 百科事典的な裏付け

search_wikipedia(query: str, max_results: int = 5) -> str

Wikipedia MediaWiki API。キー不要。高速。定義や歴史的文脈に最適。

search_academic — arXivプレプリント

search_academic(query: str, max_results: int = 5) -> str

タイトル、著者、アブストラクトの抜粋、公開日、PDFのURLを返します。キー不要。CS、物理学、数学、生物学に最適。

search_news — Hacker Newsのシグナル

search_news(query: str, max_results: int = 10) -> str

タイトル、URL、ポイント数、コメント数、日付を返します。キー不要。今テック業界でトレンドになっているものを知るのに最適。

search_stackexchange — 180以上のサイトからのQ&A

search_stackexchange(query: str, max_results: int = 5, site: str = "stackoverflow") -> str

siteを任意のSEコミュニティに設定: serverfault、superuser、askubuntu、math、tex、datascience、aiなど。キー不要。

search_scholar_meta — Crossrefによる査読付き論文

search_scholar_meta(query: str, max_results: int = 5) -> str

タイトル、DOI、被引用数、出版社、公開日、アブストラクトを返します。arXivがカバーしない論文（Elsevier、Springer、Wiley、IEEE、ACM）も対象です。キー不要。

アーキテクチャ

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│  (Claude Desktop, Hermes, Cursor, custom agent)          │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC over stdio
                     ▼
┌─────────────────────────────────────────────────────────┐
│              bin/web-research-mcp                         │
│  • Boots venv (or reuses cached one)                     │
│  • Sources web-research.env for API keys                 │
│  • Execs python -m web_research.server                   │
└────────────────────┬────────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────────┐
│           web_research.server (MCPServer)                 │
│  7 tool functions registered via @app.tool() decorator    │
│  • Pydantic-driven JSON schemas from type hints           │
│  • Single shared httpx.AsyncClient per call              │
│  • Graceful degradation: one bad source ≠ failed call    │
└────────────────────┬────────────────────────────────────┘
                     │ asyncio.gather for parallel fan-out
                     ▼
┌─────────────────────────────────────────────────────────┐
│          web_research.providers (7 backends)              │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ brave    │ │ tavily   │ │ jina_fetch  │  ← general web│
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐ ┌─────────────┐               │
│  │ wikipedia│ │ arxiv    │ │ crossref    │  ← academic   │
│  └──────────┘ └──────────┘ └─────────────┘               │
│  ┌──────────┐ ┌──────────┐                                │
│  │ hn_algolia│ │stackex   │  ← tech signal               │
│  └──────────┘ └──────────┘                                │
│  + merge_results() with URL-canonical dedup               │
└─────────────────────────────────────────────────────────┘

主要な設計判断

スクレイピング優先ではなくAPI優先。 これが中核となるテーゼです。すべてのソースは、プログラムによるアクセス用に設計された公式APIです。クリーンな構造化データが得られ、IP禁止もなく、サイトがリニューアルしてもメンテナンスの負担がありません。

ソースごとのエラー分離。 各プロバイダーはHTTP呼び出しをtry/exceptでラップしています。あるソースからの429エラーが検索全体を台無しにすることはありません。部分的な結果と、どのソースが失敗したかを示す明確なメッセージが得られます。

URL正規化。 merge_results()は重複排除の前にトラッキングパラメータ（utm_*、fbclid、gclid、ref）を除去し、ホスト名の大文字小文字を正規化し、フラグメントを削除します。BraveとTavilyが同じ記事を返した場合、also_found_in: [brave, tavily]付きで1回だけ表示され、スコアがブーストされます。

呼び出しごとの共有HTTPクライアント。 コネクションプーリング（max_connections=20）、適切なタイムアウト（デフォルト30s、fetch_urlは45s）、自動リダイレクト追従を備えたhttpx.AsyncClient。stdio MCPサーバーは一度に1つのリクエストを処理するため、クリーンな状態を保つために呼び出しごとに新しいクライアントを使用します。

ヘッドレスブラウザなし。 Playwright、Selenium、Puppeteer、プロキシローテーションは一切使用しません。攻撃対象領域が小さく、依存関係も少なく、JVM/Chromeのフットプリントもありません。JSレンダリングが必要な少数のサイトではJinaが重い処理を担当します。

代替案との比較

テスト

.venv/bin/python tests/e2e_protocol.py

これにより実際のサーバーが起動し、実際のMCP initialize + tools/listハンドシェイクを実行した後、すべてのツールに対してライブのJSON-RPC呼び出しを行い、以下を検証します:

• 実際のAPIが実際のデータを返す（スタブではない）

• 各ツールのレスポンスが期待される形状である

• エラー状態が適切に処理される

• キーなしのsearch_webが明確な「APIキーを設定してください」メッセージを返す

最終実行: 7/7ツールがライブAPIに対して合格。

トラブルシューティング

サーバーは起動するが、ツールがMCPクライアントに表示されない

hermes mcp list（または同等のコマンド）を確認してください。サーバーは--commandで登録されているため、Hermesはランチャーを直接実行します。ランチャーが実行可能であることを確認してください:

chmod +x bin/web-research-mcp

fetch_urlが切り詰められたコンテンツを返す

仕様です。2万文字の上限はコンテキストウィンドウを保護するためです。より長い読み物の場合は、ページを自分で取得して抜粋をsearch_webに渡してフォローアップの質問をするか、複数回の呼び出しでセクションに分割してください。

search_webが「Webの結果がありません。APIキーが設定されていない可能性があります」を返す

web-research.envにBRAVE_API_KEYまたはTAVILY_API_KEYの少なくとも1つを設定する必要があります。他の6つのツール（Wikipedia、arXiv、HN、Stack Exchange、Crossref、fetch_url）はすべてキーなしで動作します。

Stack Exchangeが400 Bad Requestを返す

カスタムのfilterパラメータを設定している場合、APIは不明なフィルターIDを拒否します。デフォルトのフィルターを使用してください（パラメータを省略）。必要以上に多くのフィールドが返されますが、すべて正常に動作します。このサーバーはデフォルトを使用しています。

初回起動時にサーバーがクラッシュする

stderrで実際のトレースバックを確認してください。一般的な原因: Python <3.10。python3 --versionで確認してください。

レート制限

各キー不要APIには独自の制限があります。制限に達した場合:

• Wikipedia: 約200リクエスト/分。実際のUser-Agentで身元を明かしてください（このサーバーは送信します）

• arXiv: 未認証で約1リクエスト/3秒。間隔を空けてください

• Hacker News Algolia: APIキー付きで1時間あたり1万リクエスト、キーなしで5千リクエスト

• Stack Exchange: キーなしで1日300リクエスト（リサーチセッションには十分）

• Crossref: User-Agentにmailtoを追加してください（このサーバーは追加しています）。そうすればポライトプールで無制限です

開発

プロジェクト構成

web-research-mcp/
├── bin/
│   └── web-research-mcp          # Launcher: venv bootstrap + exec
├── src/web_research/
│   ├── __init__.py
│   ├── server.py                  # MCPServer + 7 @app.tool functions
│   └── providers.py               # 7 search backends + Result dataclass
├── tests/
│   └── e2e_protocol.py            # Real subprocess JSON-RPC test
├── web-research.env.example       # API key template
├── pyproject.toml                 # PEP 621, uv-installable
├── README.md
├── CHANGELOG.md
├── LICENSE
└── .gitignore

新しいツールの追加

1. providers.pyに非同期関数を追加:

   async def search_my_source(query: str, max_results: int, client: httpx.AsyncClient) -> list[Result]:
       try:
           # ... your HTTP call ...
       except Exception as e:
           print(f"[my_source] error: {e}", flush=True)
           return []
       return [Result(title=..., url=..., snippet=..., source="my_source")]

2. server.pyに登録:

   @app.tool(name="search_my_source", description="...", annotations=ToolAnnotations(readOnlyHint=True, openWorldHint=True))
   async def search_my_source(query: Annotated[str, Field(description="Search query")], max_results: Annotated[int, Field(ge=1, le=10, default=5)] = 5) -> str:
       async with await _new_client() as client:
           res = await providers.search_my_source(query, max_results, client)
       return _format_results(query, res, "my_source") if res else f"No my_source results for: {query}"

3. tests/e2e_protocol.pyにライブテストケースを追加。

4. READMEのツールセクションを更新。

コーディングスタイル

• Python 3.10+、asyncファースト

• すべてに型ヒント。PydanticにMCP JSONスキーマを導出させる

• 各プロバイダーはネットワーク呼び出しをtry/exceptでラップし、[]に縮退させる

• 呼び出しごとのHTTPクライアント（_new_client()）— stdioモードでは呼び出し間で共有しない

コントリビューション

PR歓迎です。開く前に:

1. ライブインストールに対してe2eテストを実行: .venv/bin/python tests/e2e_protocol.py

2. 新しいツールにはテストケースを追加

3. providers.pyをMCP固有の型から独立させておく — プレーンなPythonモジュールとして再利用可能であるべき

4. ヘッドレスブラウザやプロキシローテーションへの依存を追加しない — プロジェクトのテーゼに反します

大きな変更の場合は、最初にissueを開いてください。

ライセンス

MIT — LICENSEを参照。

クレジット

• AnthropicによるModel Context Protocol上に構築

• クリーンなページ取得にJina Readerを使用

• 検索API: Brave、Tavily、Wikipedia、arXiv、Crossref、Hacker News Algolia、Stack Exchange