MCP SearXNG Enhanced Server

MCP SearXNG Enhanced サーバー

カテゴリに対応したウェブ検索、ウェブサイトのスクレイピング、日付／時刻ツールを提供する Model Context Protocol（MCP）サーバーです。SearXNG および最新の MCP クライアントとのシームレスな統合を目的に設計されています。

機能

• 🔍 カテゴリ（一般、画像、動画、ファイル、地図、ソーシャルメディア）に対応した、SearXNG を利用したウェブ検索
• 📄 引用メタデータと Reddit URL の自動変換に対応したウェブサイトコンテンツのスクレイピング
• 📜 Markdown への変換を伴う、初期段階の PDF 読み取りサポート（PyMuPDF/PyMuPDF4LLM を使用）
• 💾 自動鮮度検証機能を備えたメモリ内キャッシュ
• 🚦 サービスの不正利用を防ぐドメインベースのレート制限
• 🕒 タイムゾーンに対応した日付／時刻ツール
• ⚠️ カスタム例外型による堅牢なエラー処理
• 🐳 Docker 化され、環境変数で設定可能
• ⚙️ コンテナの再起動後も設定を保持

クイックスタート

前提条件

• システムに Docker がインストールされていること
• SearXNG インスタンスが稼働していること（セルフホストまたはアクセス可能なエンドポイント）

インストールと使い方

Docker イメージをビルドします：

docker build -t overtlids/mcp-searxng-enhanced:latest .

SearXNG インスタンスを指定して実行します（Docker を手動で実行）：

docker run -i --rm --network=host \
  -e SEARXNG_ENGINE_API_BASE_URL="http://127.0.0.1:8080/search" \
  -e DESIRED_TIMEZONE="America/New_York" \
  overtlids/mcp-searxng-enhanced:latest

この例では、SEARXNG_ENGINE_API_BASE_URL を明示的に設定しています。DESIRED_TIMEZONE も America/New_York に明示的に設定しており、これはデフォルト値と同じです。docker run コマンドで -e フラグを使って環境変数を指定しない場合、サーバーは Dockerfile で定義されたデフォルト値を自動的に使用します（下記の環境変数の表を参照してください）。そのため、DESIRED_TIMEZONE にデフォルト値を使用する場合は、-e DESIRED_TIMEZONE="America/New_York" フラグを省略できます。ただし、SEARXNG_ENGINE_API_BASE_URL は重要であり、Dockerfile のデフォルト値（http://host.docker.internal:8080/search）が適切でない場合は、通常、お使いの SearXNG インスタンスのアドレスに合わせて設定する必要があります。

Docker を手動で実行する場合の注意：このコマンドは、Docker コンテナを単独で実行します。Cline in VS Code などの MCP クライアントを使ってこのサーバーを管理する場合、クライアントは独自の設定で定義された設定を使用して、コンテナの独自のインスタンスを起動します。MCP クライアントで特定の環境変数を使用するには、このサーバーのクライアント設定内で環境変数を設定する必要があります（下記を参照）。

MCP クライアントを設定します（例：Cline in VS Code）：

MCP クライアントがこのサーバーを正しく管理して実行するには、overtlids/mcp-searxng-enhanced サーバーに必要なすべての環境変数をクライアント設定内で定義する必要があります。MCP クライアントはこれらの設定を使用して、docker run コマンドを組み立てます。

以下は、MCP クライアントの JSON 設定（例：cline_mcp_settings.json）でこのサーバーに使用する推奨デフォルト設定です。この例では、Dockerfile で定義されたデフォルト値に設定されているすべての環境変数を明示的に列挙しています。この内容をそのままコピーして貼り付け、必要に応じて値をカスタマイズできます。

{
  "mcpServers": {
    "overtlids/mcp-searxng-enhanced": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network=host",
        "-e", "SEARXNG_ENGINE_API_BASE_URL=http://host.docker.internal:8080/search",
        "-e", "DESIRED_TIMEZONE=America/New_York",
        "-e", "ODS_CONFIG_PATH=/config/ods_config.json",
        "-e", "RETURNED_SCRAPPED_PAGES_NO=3",
        "-e", "SCRAPPED_PAGES_NO=5",
        "-e", "PAGE_CONTENT_WORDS_LIMIT=5000",
        "-e", "CITATION_LINKS=True",
        "-e", "MAX_IMAGE_RESULTS=10",
        "-e", "MAX_VIDEO_RESULTS=10",
        "-e", "MAX_FILE_RESULTS=5",
        "-e", "MAX_MAP_RESULTS=5",
        "-e", "MAX_SOCIAL_RESULTS=5",
        "-e", "TRAFILATURA_TIMEOUT=15",
        "-e", "SCRAPING_TIMEOUT=20",
        "-e", "CACHE_MAXSIZE=100",
        "-e", "CACHE_TTL_MINUTES=5",
        "-e", "CACHE_MAX_AGE_MINUTES=30",
        "-e", "RATE_LIMIT_REQUESTS_PER_MINUTE=10",
        "-e", "RATE_LIMIT_TIMEOUT_SECONDS=60",
        "-e", "IGNORED_WEBSITES=",
        "overtlids/mcp-searxng-enhanced:latest"
      ],
      "timeout": 60
    }
  }
}

MCP クライアント設定の要点：

• 上記の例は、すべての環境変数をデフォルト値に設定して Docker コンテナを実行するための引数一式です。
• 設定をカスタマイズするには、MCP クライアントの設定にある args 配列内の該当する -e "VARIABLE_NAME=value" 行の値を変更するだけです。たとえば、SEARXNG_ENGINE_API_BASE_URL と DESIRED_TIMEZONE を変更するには、それぞれの行を調整します。
• 各変数とそのデフォルト値の詳しい説明については、下記の「環境変数」の表を参照してください。
• サーバーの動作は、主にこれらの環境変数で制御されます。ods_config.json ファイルも設定に影響することがありますが（「設定管理」を参照）、MCP クライアントから渡された環境変数が優先されます。

HTTP サーバーモード（FastMCP）

デフォルトの stdio トランスポートに加えて、サーバーはFastMCPを使用して、HTTP 経由で MCP エンドポイントを公開できます。これは、サブプロセスを起動するのではなく、HTTP 経由で接続するクライアントに便利です。

HTTP サーバーの起動

python mcp_server.py --http

サーバーはデフォルトで 0.0.0.0:8000 で起動し、次の場所で MCP リクエストを受け付けます。

http://<host>:<port>/mcp

すべてのオリジンが許可されるため（CORS は完全にオープンです）、このエンドポイントには、あらゆるクライアントやブラウザーベースのツールからアクセスできます。

HTTP サーバーの環境変数

変数	説明	デフォルト
MCP_HTTP_HOST	バインドするホストアドレス	0.0.0.0
MCP_HTTP_PORT	リッスンするポート	8000

例 — ホストとポートを指定する場合：

MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=9000 python mcp_server.py --http

Windows（コマンドプロンプト）：

set MCP_HTTP_HOST=127.0.0.1
set MCP_HTTP_PORT=9000
python mcp_server.py --http

Windows（PowerShell）：

$env:MCP_HTTP_HOST="127.0.0.1"
$env:MCP_HTTP_PORT="9000"
python mcp_server.py --http

MCP クライアントを HTTP 経由で接続する

MCP クライアントの接続先を /mcp エンドポイントに設定します。

{
  "mcpServers": {
    "mcp-searxng-enhanced-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

注： すべてのサーバー設定変数（SEARXNG_ENGINE_API_BASE_URL、DESIRED_TIMEZONE など）は、stdio モードの場合と同様に HTTP モードでも適用されます。ods_config.json ファイルは、サーバーが接続の受け付けを開始する前の起動時に書き込まれます。

---

ネイティブで実行する（Docker を使用しない場合）

Docker を使用せずに Python でサーバーを直接実行する場合は、以下の手順に従ってください。

1. Python のインストール：

• このサーバーには Python 3.9 以降が必要です。Python 3.11（Docker イメージで使用されているバージョン）を推奨します。
• Python は python.org からダウンロードできます。

2. リポジトリのクローン：

• GitHub からコードを取得します。

  git clone https://github.com/OvertliDS/mcp-searxng-enhanced.git
  cd mcp-searxng-enhanced
  

3. 仮想環境の作成と有効化（推奨）：

• 仮想環境を使用すると、依存関係を管理し、他の Python プロジェクトとの競合を避けやすくなります。

  # For Linux/macOS
  python3 -m venv .venv
  source .venv/bin/activate
  
  # For Windows (Command Prompt)
  python -m venv .venv
  .\.venv\Scripts\activate.bat
  
  # For Windows (PowerShell)
  python -m venv .venv
  .\.venv\Scripts\Activate.ps1
  

4. 依存関係のインストール：

• 必要な Python パッケージをインストールします。

  pip install -r requirements.txt
  

  主な依存関係には、httpx、BeautifulSoup4、pydantic、trafilatura、python-dateutil、cachetools、zoneinfo、filetype、pymupdf、pymupdf4llm、fastmcp が含まれます。

5. SearXNG にアクセスできることを確認する：

• 引き続き、稼働中の SearXNG インスタンスが必要です。API のベース URL（例：http://127.0.0.1:8080/search）を確認してください。

6. 環境変数の設定：

• サーバーは環境変数で設定します。最低限、SEARXNG_ENGINE_API_BASE_URL を設定する必要があります。
• Linux/macOS（bash/zsh）：

  export SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
  export DESIRED_TIMEZONE="America/Los_Angeles"
  

• Windows（Command Prompt）：

  set SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
  set DESIRED_TIMEZONE="America/Los_Angeles"
  

• Windows（PowerShell）：

  $env:SEARXNG_ENGINE_API_BASE_URL="http://your-searxng-instance:port/search"
  $env:DESIRED_TIMEZONE="America/Los_Angeles"
  

• 利用可能なすべてのオプションについては、以下の「環境変数」テーブルを参照してください。設定されていない場合は、スクリプトのデフォルト値、または（ルートディレクトリか ODS_CONFIG_PATH に指定された場所にある）ods_config.json ファイルの値が使用されます。

7. サーバーの実行：

• stdio モード（デフォルト — サブプロセスを起動する MCP クライアント向け）：

  python mcp_server.py
  

  サーバーは stdin/stdout 経由で MCP クライアントからの接続を待ち受けます。

• HTTP モード（HTTP 経由で接続する MCP クライアント向け）：

  python mcp_server.py --http
  

  サーバーは http://0.0.0.0:8000/mcp で FastMCP HTTP エンドポイントを起動します。設定オプションについては、HTTP サーバーモードを参照してください。

8. 設定ファイル（ods_config.json）：

• 環境変数の代わりに、または環境変数と併用して、プロジェクトのルートディレクトリ（または環境変数 ODS_CONFIG_PATH で指定したパス）に ods_config.json ファイルを作成できます。環境変数は常にこのファイル内の値より優先されます。例： json { "searxng_engine_api_base_url": "http://127.0.0.1:8080/search", "desired_timezone": "America/New_York" }

環境変数

以下の環境変数でサーバーの動作を制御します。MCP クライアントの設定（クライアント管理のサーバーで推奨）または Docker を手動で実行する際に設定できます。

変数	説明	デフォルト（Dockerfile から）	備考
SEARXNG_ENGINE_API_BASE_URL	SearXNG の検索エンドポイント	http://host.docker.internal:8080/search	サーバーの動作に不可欠です
MCP_HTTP_HOST	HTTP サーバーモードのバインドアドレス	0.0.0.0	--http を指定して起動する場合のみ使用されます
MCP_HTTP_PORT	HTTP サーバーモードのポート	8000	--http を指定して起動する場合のみ使用されます
DESIRED_TIMEZONE	日付／時刻ツールのタイムゾーン	America/New_York	例：America/Los_Angeles。tz データベースのタイムゾーン一覧：https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
ODS_CONFIG_PATH	永続的な設定ファイルのパス	/config/ods_config.json	通常、コンテナ内ではデフォルトのままにします。
RETURNED_SCRAPPED_PAGES_NO	検索ごとに返すページの最大数	3
SCRAPPED_PAGES_NO	スクレイピングを試行するページの最大数	5
PAGE_CONTENT_WORDS_LIMIT	スクレイピングしたページごとの最大語数	5000
CITATION_LINKS	引用イベントの有効／無効	True	True または False
MAX_IMAGE_RESULTS	返す画像結果の最大数	10
MAX_VIDEO_RESULTS	返す動画結果の最大数	10
MAX_FILE_RESULTS	返すファイル結果の最大数	5
MAX_MAP_RESULTS	返す地図結果の最大数	5
MAX_SOCIAL_RESULTS	返すソーシャルメディア結果の最大数	5
TRAFILATURA_TIMEOUT	コンテンツ抽出のタイムアウト（秒）	15
SCRAPING_TIMEOUT	HTTP リクエストのタイムアウト（秒）	20
CACHE_MAXSIZE	キャッシュするウェブサイトの最大数	100
CACHE_TTL_MINUTES	キャッシュの有効期間（分）	5
CACHE_MAX_AGE_MINUTES	キャッシュコンテンツの最大経過時間（分）	30
RATE_LIMIT_REQUESTS_PER_MINUTE	ドメインごとの1分あたりの最大リクエスト数	10
RATE_LIMIT_TIMEOUT_SECONDS	レート制限の追跡期間（秒）	60
IGNORED_WEBSITES	無視するサイトのカンマ区切りリスト	""（空）	例："example.com,another.org"

設定管理

サーバーでは、3 層の設定方式を採用しています。

1. スクリプトのデフォルト値（Python にハードコードされています）
2. 設定ファイル（ODS_CONFIG_PATH から読み込まれます。デフォルトは /config/ods_config.json です）
3. 環境変数（最も優先度が高い設定です）

設定ファイルが更新されるのは、次の場合に限られます。

• ファイルがまだ存在しない場合（初回の初期化）
• 現在の実行に対して環境変数が明示的に指定された場合

これにより、新しい環境変数が設定されていない場合、コンテナの再起動後もユーザー設定が維持されます。

ツールとエイリアス

ツール名	用途	エイリアス
search_web	SearXNG によるウェブ検索	search、web_search、find、lookup_web、search_online、access_internet、lookup*
get_website	ウェブサイトのコンテンツをスクレイピング	fetch_url、scrape_page、get、load_website、lookup*
get_current_datetime	現在の日付と時刻	current_time、get_time、current_date

*lookup はコンテキストに応じて動作します。

• url 引数を指定して呼び出すと、get_website に割り当てられます
• それ以外の場合は、search_web に割り当てられます

例：ツールの呼び出し

ウェブ検索

{ "name": "search_web", "arguments": { "query": "open source ai" } }

または、エイリアスを使用します。

{ "name": "search", "arguments": { "query": "open source ai" } }

カテゴリ別検索

{ "name": "search_web", "arguments": { "query": "landscapes", "category": "images" } }

ウェブサイトのスクレイピング

{ "name": "get_website", "arguments": { "url": "example.com" } }

または、エイリアスを使用します。

{ "name": "lookup", "arguments": { "url": "example.com" } }

現在の日付と時刻

{ "name": "get_current_datetime", "arguments": {} }

または：

{ "name": "current_time", "arguments": {} }

高度な機能

カテゴリ別検索

search_web ツールでは、出力を最適化したさまざまなカテゴリを利用できます。

• images：画像 URL、タイトル、ソースページを返します。オプションで Markdown 埋め込みにも対応します
• videos：タイトル、ソース、埋め込み URL などの動画情報を返します
• files：形式やサイズなど、ダウンロード可能なファイルの情報を返します
• map：座標や住所などの位置情報を返します
• social media：ソーシャルプラットフォームの投稿やプロフィールを返します
• general：デフォルトのカテゴリです。ウェブページのコンテンツをスクレイピングし、全体を返します

Reddit URL の変換

Reddit のコンテンツをスクレイピングする際、コンテンツをより適切に抽出できるよう、URL は自動的に old.reddit.com ドメインを使用する形式に変換されます。

レート制限

ドメイン単位のレート制限により、一定時間内に同じドメインへ過剰なリクエストが送信されるのを防ぎます。これにより、対象ウェブサイトへの過負荷や IP ブロックの可能性を抑えます。

キャッシュの検証

キャッシュされたウェブサイトのコンテンツは、経過時間に基づいて鮮度が自動的に検証されます。古くなったコンテンツは自動的に更新され、有効なキャッシュコンテンツはすばやく提供されます。

エラー処理

サーバーには、次の例外タイプを使用する堅牢なエラー処理システムが実装されています。

• MCPServerError：すべてのサーバーエラーの基底例外クラス
• ConfigurationError：設定値が無効な場合に発生します
• SearXNGConnectionError：SearXNG への接続に失敗した場合に発生します
• WebScrapingError：ウェブスクレイピングに失敗した場合に発生します
• RateLimitExceededError：ドメインのレート制限を超過した場合に発生します

エラーは、内容がわかるメッセージとともにクライアントへ適切に伝播されます。

トラブルシューティング

• SearXNG に接続できない場合：SearXNG のインスタンスが実行中であり、環境変数 SEARXNG_ENGINE_API_BASE_URL が正しいエンドポイントを指していることを確認してください。
• レート制限エラー：レート制限エラーが頻発する場合は、RATE_LIMIT_REQUESTS_PER_MINUTE を調整してください。
• コンテンツ抽出が遅い場合：複雑なページのコンテンツ処理に時間がかかる場合は、TRAFILATURA_TIMEOUT を増やしてください。
• Docker のネットワークに関する問題：Windows／Mac で Docker Desktop を使用している場合、host.docker.internal でホストマシンを参照できます。Linux では、代わりにホストの IP アドレスを使用する必要がある場合があります。
• HTTP モードに接続できない場合：ファイアウォールが MCP_HTTP_PORT（デフォルトは 8000）をブロックしていないことを確認してください。すべてのインターフェースでバインドするには MCP_HTTP_HOST=0.0.0.0 を設定し、localhost のみに制限するには 127.0.0.1 を設定してください。
• HTTP モードでセッション ID エラーが発生する場合：サーバーはステートレス HTTP モードで動作し、/mcp への各 POST は単独で完結します。クライアントがセッションベースのトランスポートを必要とする場合は、代わりに stdio モードに切り替えてください。

謝辞

以下に着想を得ています：

• SearXNG - プライバシーを尊重するメタ検索エンジン
• Trafilatura - テキスト抽出用のウェブスクレイピングツール
• ihor-sokoliuk/mcp-searxng - SearXNG 用のオリジナル MCP サーバー
• nnaoycurt (Better Web Search Tool)
• @bwoodruff2021 (GetTimeDate Tool)

ライセンス

MIT License © 2025 OvertliDS