mcp-retrieval

概要

mcp-retrieval はGoで書かれた Model Context Protocol サーバーです。Web取得機能を、MCP互換の任意のクライアント（Claude Desktop、IDEエージェント、カスタムLLMアプリ）に3つの読み取り専用ツールとして公開します。内部では retrieval-go ライブラリを使用してWeb検索とページ取得を行い、結果をモデルに渡す準備の整ったクリーンなMarkdownとして返します。

このライブラリは APIキーを必要としません。Web検索はDuckDuckGo Lite、画像検索はBing Imagesを経由し、ページ取得ではHTMLを可読性抽出器（readability extractor）に通してからMarkdownに変換します。ボット対策に対して信頼性を保つため、TLSレベルで実際のブラウザを模倣し、ブラウザフィンガープリントとプロキシの両方をローテーションできます — 取得エンジン を参照してください。

MCP SDKがサポートする両方のトランスポートが利用可能で、どちらも同一のツールセットを公開します。

• stdio — クライアントがバイナリを起動し、stdin/stdoutで通信します（デフォルト。デスクトップクライアントに最適）。

• http — 長時間実行されるストリーミング可能なHTTPサーバー（リモート/共有デプロイに便利）。

Related MCP server: mcp-web-calc

ツール

3つすべてが 読み取り専用 として注釈付けされています。各ツールは出力スキーマに一致する構造化JSONペイロードを返します。SDKは structuredContent を読み取らないクライアントのために、同じJSONをテキストコンテンツブロックにもミラーリングします。

web_search

web_search_images

web_scrape

queries/urls の両リストは、呼び出しごとに max_queries（10）項目までに制限されます。クエリは512文字以下、URLは2048文字以下かつ http/https のみである必要があります。

結果と件数

すべての呼び出しは入力リスト全体にファンアウトし、クエリ/URLごとに1エントリを返します。各エントリには独自の status — success、failed、timeout — があり、部分的な失敗でも成功した項目は返されます。

count は実際に返された項目数で、要求した max_results / max_images より 少なくなることがあります。単一クエリの結果内の重複は上限が適用される前に除去され、また上流が単純に提供できる項目が少ない場合もあります。count が小さいのは正常な結果であり、エラーではありません。

重複排除は クエリごとであり、クエリ間では行われません。各エントリは個別に重複排除されるため、同じ呼び出し内の2つのクエリで見つかったリンクは両方のエントリに現れます。必要であれば、自分で和集合の重複排除を行ってください。

エラー

リクエストレベルの失敗は、JSON-RPCエラーではなく、isError: true とプレーンテキストメッセージを持つツール結果として返されます。モデルはメッセージを読み、呼び出し自体を修正できます。項目ごとの失敗はこのようにはならず、ペイロード内に status: "failed" / "timeout" として留まります。

呼び出しが完全に失敗するのは、入力が作業開始前に拒否された場合、または すべての 項目が失敗した場合のみです。

全失敗メッセージは意図的にタイムアウトと他の原因を区別しません。混合バッチは複数の理由で同時に失敗し得るため、少なくとも1つの項目が生き残る場合は、項目ごとの status がすでにその詳細を保持しています。

既知の制限

• web_scrape はHTMLのみを処理します。 ページは可読性抽出器に通されますが、これには記事マークアップが必要なため、text/plain 応答は何も生成せず、status: "failed" として返されます。生ファイルのホストが一般的なケースです: raw.githubusercontent.com、github.com/.../raw/...、cdn.jsdelivr.net。生ファイルではなくレンダリングされたページをスクレイピングしてください。

• web_search_images の関連性は保証されません。 一部のクエリでは、Bing Imagesが結果セットではないページを提供し、それが結果セットとして解析されます — その場合、ツールは無関係な画像を status: "success" で返します。画像結果はベストエフォートとして扱い、ユーザーに表示する前に検証してください。

• JavaScriptは実行されません。 ページはそのまま取得されます。クライアントサイドでレンダリングされるコンテンツは抽出器からは見えません。

クイックスタート

インストール

どれでもお好みのものを選んでください — すべて同一のサーバーが得られます。

コンテナ（Goツールチェーン不要）:

docker pull ghcr.io/role1776/mcp-retrieval:latest

プリビルドバイナリ — 最新リリース からお使いのプラットフォームのアーカイブを取得し、解凍して mcp-retrieval を PATH に配置します。

MCPバンドル — .mcpb ファイルをインストールするクライアント向けに、最新リリース から mcp-retrieval_<version>_<os>_<arch>.mcpb をダウンロードし、クライアントで開きます。バンドルにはコンパイル済みバイナリが含まれているため、DockerもGoも不要です。OS と CPUアーキテクチャの両方に一致するファイルを選択してください。バンドルにはネイティブバイナリが1つだけ含まれています。

ソースから:

go install github.com/Role1776/mcp-retrieval/app/cmd/mcp-retrieval@latest   # needs Go 1.25.5+

または、その場でバイナリをビルドします（Goモジュールは app/ にあります）:

make build          # -> bin/mcp-retrieval

実行

# defaults: stdio transport, no configuration needed
./bin/mcp-retrieval

# with an explicit env file
./bin/mcp-retrieval -env /absolute/path/to/.env

フラグは1つだけで、オプションです:

MCPクライアントの接続（stdio）

クライアントをビルド済みバイナリに向けます。Claude Desktop設定の例:

{
  "mcpServers": {
    "retrieval": {
      "command": "/absolute/path/to/mcp-retrieval",
      "env": {
        "MAX_RESULTS": "20"
      }
    }
  }
}

envブロックは省略可能です — "command"だけで十分です。

MCPクライアントへの接続（コンテナ）

stdioでイメージを実行します。設定は引き続きenvブロックを通じて渡されますが、Dockerでは各変数をコマンドラインで-eを使って指定してプロセスに到達させる必要があります:

{
  "mcpServers": {
    "retrieval": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MAX_RESULTS",
        "-e", "DEFAULT_TIMEOUT_MS",
        "ghcr.io/role1776/mcp-retrieval:latest"
      ],
      "env": {
        "MAX_RESULTS": "20",
        "DEFAULT_TIMEOUT_MS": "5000"
      }
    }
  }
}

-iは必須です — これがないとコンテナはstdinを受け取れず、クライアントはサーバーが即座に終了するのを目にします。MCP Registryからインストールするクライアントは、この呼び出しを自分で構築し、server.jsonで宣言された変数をプロンプトで尋ねます。

HTTP経由での実行

MCP_TRANSPORT=httpを設定すると、サーバーはSERVER_PORTのMCP_PATH（デフォルトはhttp://localhost:8080/mcp）で待ち受けます。

設定

すべては環境変数を通じて設定され、各値は起動前に検証されます: 数値でない値や正でない値は起動エラーになります。制限値間の関係は起動時にはチェックされません — 制限を参照してください。環境に既に存在する変数は.envファイルより優先されるため、MCPクライアントのenvブロックは常に有効になります。すべてのフィールドには適切なデフォルト値があるため、サーバーは設定なしでも（stdioトランスポートで）動作します。

デフォルト値での完全なリストは、.envにコピーできる状態で.env.exampleを参照してください。

MCPサーバー

クライアントに通知されるバージョンは設定できません: ビルド時にgitタグからバイナリに刻印されます。

HTTPサーバー（httpトランスポートのみ）

HTTPクライアントとプロキシ

プロキシが設定されている場合、各送信リクエストにはログインに一意のセッションIDが追加されるため、アップストリームプロバイダーはリクエストごとに出口IPをローテーションします。

制限

各値は個別にチェックされます — ゼロより大きくなければなりません — ただし、DEFAULT_*、MIN_*、MAX_*の3つ組は起動時に相互チェックされません。一貫性のないセットでもサーバーは停止しません。代わりにリクエストごとに調整されます:

• 呼び出し元が省略した値、またはゼロや負の値で渡された値は、対応するDEFAULT_*にフォールバックします;

• 結果は[MIN_*, MAX_*]にクランプされるため、DEFAULT_*がMAX_*より大きい場合は単純にMAX_*になります;

• MIN_*がMAX_*を超える場合は、最大値が優先されます。

したがって、有効な制限は常に設定された最大値以内に収まり、設定ミスは起動失敗ではなく動作するサーバーへの劣化になります。トレードオフは、それが静かに劣化することです: MAX_RESULTS=2のようなタイプミス（20の代わり）は警告を生成せず、静かに応答が小さくなるだけです。結果が切り詰められているように見える場合は、これらの値を再確認する価値があります。

ロギング

アーキテクチャ

このプロジェクトはクリーンで階層化された構造に従っています。依存関係はドメインに向かって内側を向き、各レイヤーはインターフェースを通じて次のレイヤーと通信します。

app/                       the Go module: sources plus its build files
                           (Dockerfile, .dockerignore, .goreleaser.yaml)

cmd/mcp-retrieval/main.go  entry point: parse flags, load config, run app

internal/
  app/                     wiring + lifecycle (build server, run, graceful shutdown)
  config/                  config loading (.env → env vars → validate)
  domain/                  core types (Query, Link, Document, Snippet, Image) and errors
  dto/web/                 request/response shapes for the MCP tools
  transport/mcp/           MCP layer
    router/                registers every tool group on the MCP server
    web/                   tool handlers
    utils/                 schema helpers and error → tool-result mapping
  usecase/web/             business logic: validation, parallelism, timeouts, dedupe/limit/rerank
  adapter/web/             retrieval-go client wiring (search, images, scrape, proxy)
  pkg/                     reusable building blocks (mcpserver, server, logger, validator)

ツール呼び出しのリクエストフロー:

MCP client → transport/mcp/web (handler) → usecase/web → adapter/web → retrieval-go → the web
                     ↑ maps errors               ↑ validates, fans out, limits results

検索とスクレイピングはどちらも入力リスト全体で並行してファンアウトし、各項目の結果を集約します。各項目には独自のステータス（success、failed、timeout）があります。呼び出しが完全に失敗するのは、その中のすべての項目が失敗した場合のみです。

検索エンジン

すべてのネットワーク処理はretrieval-goに委任され、app/internal/adapter/webで設定されます。知っておくべきこと:

• ソース。 Web検索はDuckDuckGo Liteを使用します; 画像検索はBing Imagesを使用します; ページ取得は生のHTMLをreadability抽出器で処理し、メイン記事をMarkdownに変換します（テーブルを含む）。検索エンジンのAPIキーは不要です。

• ブラウザ偽装。 アダプターはWithBrowserRotation()を有効にするため、各リクエストはランダムに選択された約11の実ブラウザプロファイルのいずれかから送信されます。各プロファイルは、本物のTLS/JA3フィンガープリント（uTLS経由）と、それに一致するUser-Agentおよびクライアントヒントヘッダーを組み合わせます — Chrome 133/131/120（Windows/macOS/Linux）、Edge 131、Firefox 120（Windows/macOS）、Safari 18.4（macOS）、およびiOS 18.4 Safari。これにより、トラフィックはGoのHTTPクライアントではなく通常のブラウザのように見えます。これが無料ソースに到達可能であり続ける理由です。

• プロキシローテーション。 PROXY_HOSTが設定されている場合、アダプターはリクエストごとにプロキシのユーザー名に一意のsession-<id>を追加するプロキシファクトリーをインストールします。セッションベースの住宅用/ローテーションプロキシプロバイダーを使用すると、リクエストごとに新しい出口IPが得られ、負荷が分散されレート制限が回避されます。プロキシがない場合、リクエストは直接送信されます。

• レスポンス処理。 レスポンスは透過的に解凍され（gzip、br、zstd、deflate）、キープアライブは無効化されます（WithDisableKeepAlive()）。これにより、プールされた接続がリクエスト間で単一のフィンガープリント/IPに固定されません。

これらは動作するために設定を必要としません — 上記のデフォルトが自動的に適用されます。プロキシ認証情報のみがオプションの追加要素です。

開発

Go関連のものはすべてapp/にあるため、リポジトリルートからmakefileを使用するか、ツールチェーンに-C appを渡します:

make build          # compile the binary
make test           # run tests

go -C app build ./...      # compile everything
go -C app test ./...       # run tests
go -C app vet ./...        # static checks

プルリクエストのガイドラインについてはCONTRIBUTING.mdを参照してください。

ライセンス

MIT Licenseの下でリリースされています。