Onion Search

darkweb-mcp (onion-search-mcp)

onion サービスを検索し、Tor 経由でページを読み取るローカルの Python stdio MCP サーバーです。5 つのツール、8 つの検索アダプター、メモリーキャッシュ、2 つの MCP リソースを提供します。

重要

プライバシー： 機密性の高い検索にはローカルモデルを使用してください。クラウドモデルは、MCP クライアントを通じてクエリや取得したコンテンツを受け取る可能性があります。クライアントのログ記録、テレメトリー、クラウドへのフォールバック設定を確認してください。

警告

ユーザーの責任： ご自身の行動および適用される法律の遵守については、ご自身が責任を負います。著者およびコントリビューターは、法律で認められる範囲において、本ソフトウェアの使用または誤用に関する責任を否認します。

実行

2 コンテナー構成では、MCP プロセスに内部 Docker ネットワークが割り当てられます。外部への経路を持つのは Tor コンテナーだけです。

docker compose build
docker compose up -d tor
docker compose run --rm --no-deps -T server

サーバーを起動する前に、docker compose ps で Tor が正常な状態であることを確認してください。サーバーは MCP メッセージに stdin と stdout を使用します。stdout はクライアントに接続したままにしてください。 Tor を含む単一コンテナーの場合：

docker run -i --rm --read-only --cap-drop ALL --security-opt no-new-privileges:true --tmpfs /tmp:rw,noexec,nosuid,size=96m,uid=10001,gid=10001,mode=1770 --memory 768m --cpus 2 onion-search-mcp:local

同梱コンテナーには Tor が必要とする外部への経路があります。サーバーと Tor のネットワークを分離するには Compose を使用してください。Tor の初回ブートストラップには数分かかることがあります。 Linux に Python をローカルインストールする場合は、Tor と libseccomp2 をインストールしてから、次を実行します。

uv sync --frozen
uv run onion-search-mcp --bundled-tor

既存の Tor プロセスを使用するには、SocksPort 9050 IsolateSOCKSAuth、ControlPort 9051、およびコントロール認証を設定してから、uv run onion-search-mcp を実行します。必要に応じて TOR_CONTROL_PASSWORD または TOR_COOKIE_FILE を設定してください。

コンテンツフィルターの切り替え

フィルタリングはデフォルトで有効です。環境設定または CLI オプションを使って、プロセスのフィルタリングを無効または有効にできます。

CONTENT_FILTER=false uv run onion-search-mcp
uv run onion-search-mcp --no-content-filter
uv run onion-search-mcp --content-filter
CONTENT_FILTER=false docker compose run --rm --no-deps -T server

各コンテンツツールでは content_filter も指定できます。呼び出し時にフィルタリングを無効にするには false を、有効にするには true を渡します。省略すると、プロセスの設定が使用されます。

{"name":"onion_fetch","arguments":{"url":"http://YOUR_56_CHARACTER_ADDRESS.onion/","content_filter":false}}

この切り替えは、ドメインのブロックリストとキーワードルールを制御します。Tor 経由のルーティング、URL の検証、テキストのみの取得、パーサーの制限、信頼できないコンテンツのラップは常に適用されます。検索エンジンが独自のフィルタリングを適用する場合があります。キャッシュエントリーはフィルター設定ごとに分けられます。

MCP クライアントの設定

docker compose up -d tor で Tor サイドカーを起動してから、stdio クライアントを設定します。

{
  "mcpServers": {
    "onion-search": {
      "command": "docker",
      "args": ["compose", "--project-directory", "/absolute/path/to/onion", "run", "--rm", "--no-deps", "-T", "server"]
    }
  }
}

同梱イメージの場合は、コマンドと引数に docker run -i --rm onion-search-mcp:local を指定してください。Python の場合は、uv --directory /absolute/path/to/onion run --frozen onion-search-mcp を使用してください。ツールの承認はクライアントで設定します。

ツール

ツール	引数	出力
onion_search	query, engines, limit=20, page=1, content_filter	ランク付けされた結果、一致度、ソースレコード、失敗したエンジン
onion_fetch	url, max_chars=20000, include_links=true, content_filter	Markdown テキスト、タイトル、リンク、レスポンスメタデータ
onion_status	url, timeout_s=30, content_filter	到達可能性、HTTP ステータス、レイテンシ、エラーコード
onion_links	url, onion_only=true, content_filter	Onion リンクと、任意でクリアネットリンク（リンク先へのアクセスは行いません）
tor_health	なし	SOCKS ハンドシェイク、ブートストラップの進捗率、Tor のバージョン
onion://engines には、有効なアダプター、アドレス、検証状態、最新の観測されたヘルス状態が記載されています。onion://history には、このプロセスでの直近100件のクエリが含まれています。どちらもメモリーリソースです。
ソースには、エンジン、URL、UTC の取得時刻、Tor が報告した場合はサーキット ID が含まれます。サーキット ID がない場合は null です。キャッシュされたソースには、元の取得時刻が保持されます。up=true は、4xx や 5xx のレスポンスを含め、HTTP レスポンスを受信したことを意味します。exit_check=false は、クリアネットへの出口チェックが行われなかったことを意味します。Onion サービスでは出口リレーを使用しません。
検索クエリはトリミングされ、最大256文字に制限されます。結果数は1～50件、ページ数は1～10000、取得テキストは1～200000文字、ステータスタイムアウトは1～120秒です。受け付けられるのは、ホスト部分が56文字の base32 Onion ホストである HTTP(S) URL のみです。認証情報、v2 ホスト、IP ホスト、その他のスキーム、クリアネットへのリダイレクトは拒否されます。
テキスト以外のレスポンスでは、本文を消費せずにメタデータと UNSUPPORTED_CONTENT を返します。ブロックされた取得では、blocked=true と空のコンテンツを返します。ブロックされた結果と外部リンクは除外されます。必須キーワードに一致した場合、ページ全体が非表示になります。既知のブロック対象ドメインは、返されたテキスト内で伏せ字にされます。

設定

変数	デフォルト	用途
TOR_SOCKS	127.0.0.1:9050	数値形式のプロキシ IP とポート。ローカル DNS は使用しません
TOR_CONTROL	127.0.0.1:9051	数値形式のコントロール IP とポート
TOR_CONTROL_PASSWORD	unset	コントロールパスワード。Compose ではローカル用のデフォルト値が設定されます
TOR_COOKIE_FILE	unset	SAFECOOKIE 認証ファイル
TOR_BRIDGES	empty	改行またはセミコロンで区切ったブリッジ行
ENGINES	all	設定済みエンジン識別子をカンマ区切りで指定します
ENGINES_FILE	engines.yaml	エンジン設定。パッケージに含まれる設定がフォールバックとして使用されます
BLOCKLIST_PATHS	blocklists/csam.txt	プレーンなドメインまたは MD5 のブロックリストをカンマ区切りで指定します
CONTENT_FILTER	true	すべてのコンテンツツールのデフォルト設定
TERMS_FILE	blocklists/terms.txt	必須の用語リスト。パッケージに含まれるリストがフォールバックとして使用されます
KEYWORD_FILTER	false	追加のキーワードルールを有効にします
FILTER_KEYWORDS	empty	追加の文字列をカンマ区切りで指定します
MAX_FETCH_BYTES	5242880	生データおよび展開後のレスポンスバイト数の上限
CACHE_TTL_S	900	検索 TTL。ゼロにすると両方のキャッシュが無効になります
FETCH_CACHE_TTL_S	600	フェッチ TTL
CACHE_MAX_ENTRIES	128	キャッシュごとの最大エントリ数
CACHE_MAX_BYTES	33554432	キャッシュごとのシリアライズ後の最大バイト数
ENGINE_RATE_LIMIT_S	3	エンジンごとの最小間隔
JITTER_S	2	最大ランダム分散遅延
ENGINE_TIMEOUT_S	25	エンジンごとの期限
SEARCH_TIMEOUT_S	40	全エンジンへの分散検索全体の期限
REQUEST_TIMEOUT_S	40	リクエスト全体の期限
LOG_QUERIES	false	true は拒否されます。ディスクへの履歴保存はありません
8 つすべてのアダプターが有効です：ahmia、torch、haystak、onionland、tor66、excavator、deep_search、onion_search_engine。アドレスとリクエストパラメーターは YAML に保存されています。コンテナーのデフォルトを変更するには、そのファイルを編集してイメージを再ビルドしてください。ホストディレクトリはマウントされません。
使用前に、各運営者が公開しているアドレスと現在のアドレスを照合してください。--verify-engines は Tor 経由で到達可能かどうかを確認します。運営者の本人性を確認するものではありません。確認に用いた証拠と現在の制約については、エンジンの検証を参照してください。
ブロックリストはスナップショットです。自動ダウンロードや更新確認は行われません。ソースと更新手順については、ブロックリストの由来を参照してください。
ブリッジは Tor コンテナーで TOR_BRIDGES を通じて設定します。obfs4 と Snowflake の実行ファイルが含まれています。信頼できるソースから最新のブリッジ行を入手して設定し、サイドカーを再作成してください。

プライバシーと制限

すべての HTTP リクエストは SOCKS 経由でリモート DNS を使用し、ランダムなプロセスセッションと各接続先から導出された認証情報を使います。Tor では IsolateSOCKSAuth を使用する必要があります。SOCKS 認証情報によってストリームは分離されますが、リクエストごとに物理回線が新しくなることは保証されません。シャットダウン時に NEWNYM を要求しますが、Tor によりそのシグナルがレート制限される場合があります。 HTTP クライアントは Cookie を保存せず、Referer も送信しません。GET リクエストのみを実行します。JavaScript の実行、フォームの送信、リンクの自動追跡、画像の表示、メディアのデコードは行いません。レスポンスはバイト数の上限、読み取り期限、合計期限を設けてストリーミングします。リクエストを行う前にリダイレクト先を検証します。 HTML の解析は、アドレス空間を 384 MiB、CPU 時間を 8 秒、期限を 10 秒に制限し、ネットワークシステムコールを拒否する seccomp ルールを適用した、独立した Linux プロセスで実行します。スクリプト、スタイル、コメント、埋め込みオブジェクト、非表示の要素は削除されます。信頼されていないテキストは、新しい区切り文字で囲みます。これらの対策によって、ページにプロンプトインジェクションが含まれないことや、リンクが正当であることが証明されるわけではありません。 クエリ履歴とキャッシュはメモリ内に保持され、シャットダウン時に消去されます。テレメトリー、クエリのログ記録、ディスクキャッシュ、実行時の更新確認は実装されていません。MCP クライアントとモデルランタイムには、それぞれ独自のストレージおよびネットワーク動作があります。上記のプライバシーに関する注意事項を参照してください。 ブロックリストや文字列キーワードでは、あらゆる有害なコンテンツを検出できるわけではありません。リンクは調査の手掛かりであり、複数のエンジンで一致することは順位付けの指標です。

開発

uv sync --frozen
uv run ruff check .
uv run pytest -q -m 'not integration'
docker compose config --quiet
uv build

ユニットテストでは、保存済みのパーサーフィクスチャとローカル SOCKS シミュレーターを使用します。リークテストではプロキシを停止し、接続先がローカルプロキシのみであり、接続先の DNS や直接の HTTP 接続がないことを確認します。CI では、プライベートなローカル Tor ネットワークで統合テストを実行します。テストでは、フィクスチャのみを含む一時的な onion サービスを公開します。パブリック検索エンジンへのクエリや、第三者の onion ページの読み込みは一切行いません。

uv run python tests/integration/run.py

既存の Tor インスタンスは、TEST_TOR_SOCKS と TEST_TOR_CONTROL を指定して使用できます。統合テストには利用可能な Tor 回路が必要で、ネットワークが利用できない場合は失敗することがあります。テストを参照してください。 安定したエラーには、TOR_UNAVAILABLE、INVALID_ONION、BLOCKED、TIMEOUT、ALL_ENGINES_FAILED、UNSUPPORTED_CONTENT、INVALID_QUERY、INVALID_ENGINE、INVALID_INPUT、CONFIG_ERROR、RESPONSE_TOO_LARGE、REDIRECT_LIMIT、PARSE_FAILED、PARSE_TIMEOUT があります。ツールのエラーには、機密情報を除去したコードとメッセージの JSON が含まれます。一部の検索が失敗した場合は、エンジンごとのコードが含まれ、完了した検索結果が返されます。

ライセンス

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