Searxng Mcp

CLI または API | MCP | Agent

バージョン: 2.1.0

ドキュメント — インストール、デプロイ、MCPツール・Python API・コンソールスクリプトにわたる使用方法、およびSearXNGインスタンスのプロビジョニングに関するガイダンスは、公式ドキュメントで管理されています。

Related MCP server: SearXNG MCP Server

概要

Searxng Mcp は、Agentic AI向けにSearXNG検索エンジンMCPサーバーと直接インターフェースするように設計された、本番グレードのAgentおよびModel Context Protocol (MCP) サーバーです。

主な機能

• 統合されたアクションルーティングMCPツール: メソッドを最適化されたトグル可能なツールモジュールにグループ化することで、トークンオーバーヘッドを最小限に抑え、LLMコンテキストにおけるツールの肥大化を排除します。

• エンタープライズグレードのセキュリティ: Eunomiaポリシー、OIDCトークン委任、および詳細な実行コンテキスト追跡の包括的なサポート。

• 統合グラフエージェント: Agent Control Protocol (ACP) および標準Webインターフェース (AG-UI) をサポートする組み込みのPydantic AIエージェント。

• ネイティブテレメトリとトレーシング: すぐに使えるOpenTelemetryエクスポートとネイティブのLangfuseトレーシング。

CLI または API

このエージェントは、Agentic AI向けSearXNG検索エンジンMCPサーバーAPIをラップします。プログラムによる操作、または統合された実行エントリポイントを介して対話できます。

基礎となるAPIラッパー、拡張スキーマバインディング、および開発者SDKリファレンスの使用方法に関する詳細な手順は、docs/index.md で管理されています。

MCP

このサーバーは、動的なアクションルーティングツールを利用してトークンオーバーヘッドを最適化し、IDE互換性を最大化します。

利用可能なMCPツール

以下の表はMCPサーバーから自動生成されています。手動で編集しないでください。

凝縮されたアクションルーティングツール (MCP_TOOL_MODE=condensed)

4つのアクションルーティングツール・0の冗長1:1ツール。各ツールは、その<DOMAIN>TOOLトグルがfalseに設定されていない限り有効です。MCP_TOOL_MODEがサーフェスを選択します（**intentデフォルト* — 6つの動詞ツール、オンデマンドでロードされる詳細セット・condensedアクションルーティング・verbose 1:1・both）。自動生成 — 編集しないでください。*

詳細なツールスキーマ、パラメータ形状、および検証制約は、docs/usage.md に保持されています。

動的ツール選択と可視性

このMCPサーバーは、実行時の動的なツールセット選択と可視性フィルタリングをサポートしています。これにより、LLMのコンテキストウィンドウを肥大化させないために、公開されるツールのセットを制限できます。

複数の入力チャネルを介してツールフィルタリングを設定できます:

• CLI引数: 起動時に --tools または --toolsets（または、その無効化対応である --disabled-tools と --disabled-toolsets）を渡します。

• 環境変数: 標準の環境変数を定義します:

  • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS

  • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS

• HTTP SSEリクエストヘッダー: トランスポート初期化中にカスタムヘッダーを渡します:

  • x-mcp-enabled-tools / x-mcp-disabled-tools

  • x-mcp-enabled-tags / x-mcp-disabled-tags

• HTTP SSEリクエストクエリパラメータ: トランスポート接続URLにクエリパラメータを直接追加します:

  • ?tools=tool1,tool2

  • ?tags=tag1

クエリ文字列またはパラメータが指定されると、LLMフリーのナレッジグラフ解決レイヤー（DynamicToolOrchestratorを使用）が、既知のツールタグ、名前、または説明に対してクエリ意図を照合し、安全なフォールバックと自動化された24時間のバックグラウンドキャッシュ更新を提供します。

MCP設定例

コネクタ重視の[mcp]エクストラをインストールします。 例では、agent-utilities[mcp]を通じてFastMCP / FastAPIを追加するために searxng-mcp[mcp] を使用しています。必要なAgent Utilitiesコアは、引き続き epistemic-graph[full] を保持します。[agent-runtime] エクストラは、さらにモデルオーケストレーションを有効にします。

stdioトランスポート（ローカルIDE — Cursor、Claude Desktop、VS Code）

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "searxng-mcp[mcp]",
        "searxng-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "intent",
        "SEARCH_APPTOOL": "true",
        "SEARXNG_EMBEDDED": "true",
        "SEARXNG_KG_INGEST": "true",
        "USE_RANDOM_INSTANCE": "false"
      }
    }
  }
}

ランタイム参照には、GraphOSなどのエイリアス対応ランチャーが必要です。その他の ランチャーはこれらのエントリを省略し、独自のランタイムシークレット境界を通じて解決された値を注入する必要があります。

Streamable-HTTPトランスポート（ネットワーク / 本番環境）

{
  "mcpServers": {
    "searxng-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "searxng-mcp[mcp]",
        "searxng-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "127.0.0.1",
        "PORT": "8000",
        "MCP_TOOL_MODE": "intent",
        "SEARCH_APPTOOL": "true",
        "SEARXNG_EMBEDDED": "true",
        "SEARXNG_KG_INGEST": "true",
        "USE_RANDOM_INSTANCE": "false"
      }
    }
  }
}

または、url によって事前デプロイされたStreamable-HTTPインスタンスに接続します:

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

レビュー済みのコンテナイメージを、最小権限のstdio子プロセスとして実行します（ リスナーや公開ポートなし）:

docker run -i --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --pids-limit=256 \
  --tmpfs /tmp:rw,noexec,nosuid,nodev,size=64m \
  -e TRANSPORT=stdio \
  -e MCP_TOOL_MODE=intent \
  -e SEARCH_APPTOOL=true \
  -e SEARXNG_EMBEDDED=true \
  -e SEARXNG_KG_INGEST=true \
  -e USE_RANDOM_INSTANCE=false \
  registry.example.invalid/searxng-mcp@sha256:<digest> searxng-mcp

コンテナ化されたネットワークHTTPの場合は、オペレーター所有のデプロイプロファイルを通じて、認証済みTLSイングレス（または 直接サーバーTLS）、正確な MCP_ALLOWED_HOSTS、および正確な信頼済みプロキシ CIDRポリシーを提供します。ジェネレーターは、認証されていない非ループバックリスナーを発行しません。

コード読み取り環境サーフェス（MCP_TOOL_MODE + パッケージ変数）から自動生成 — 編集しないでください。

追加のデプロイオプション

searxng-mcp は、ローカルのstdioプロセスまたはコンテナとして、あるいはリモートの ネットワーク境界の背後で実行できます。 デプロイガイド には、 詳細なトランスポート契約が記載されています。

• ローカルコンテナ — レビュー済みのイミュータブルイメージを、リスナーや公開ポートのない最小権限の stdio子プロセスとして起動します。

• リモートURL — オペレーター提供の認証済みHTTPS イングレスを通じて接続します。そのURL、送信ID参照、信頼プロファイル、および正確な MCP_ALLOWED_HOSTS を AgentConfig に保持します。

Agent

このリポジトリには、完全に統合されたPydantic AIグラフエージェントが含まれています。これはAgent Control Protocol (ACP) を介して通信し、Agent Web UI (AG-UI) およびターミナルインターフェースとシームレスに連携します。

Agent CLIの実行

インタラクティブなコマンドラインエージェントを開始するには:

# Set credentials
export SEARXNG_URL="your_value"

# Run the agent server
searxng-agent --provider openai --model-id gpt-4o

Docker Composeオーケストレーション

以下の docker/agent.compose.yml は、Agent、Web UI、およびターミナルインターフェースを一緒に設定します:

version: '3.8'

services:
  searxng-mcp-mcp:
    image: example/searxng-mcp@sha256:<digest>
    container_name: searxng-mcp-mcp
    hostname: searxng-mcp-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  searxng-mcp-agent:
    image: example/searxng-mcp@sha256:<digest>
    container_name: searxng-mcp-agent
    hostname: searxng-mcp-agent
    restart: always
    depends_on:
      - searxng-mcp-mcp
    env_file:
      - ../.env
    command: [ "searxng-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9001
      - MCP_URL=http://searxng-mcp-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9001:9001"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9001/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

詳細なグラフノードアーキテクチャの説明、カスタムスキル設定、およびエージェントトレースガイドは、docs/deployment.md で入手できます。

セキュリティとガバナンス

エンタープライズ対応の agent-utilities コア上に直接構築されており、標準のセキュリティパラメータが完全にサポートされています:

アクセス制御とポリシー適用

• Eunomiaポリシー: きめ細かい、ポリシー駆動のツール認証。none、ローカル embedded (mcp_policies.json)、または集中型 remote モードをサポートします。

• OIDCトークン委任: Web UI / ACP → Agent → MCP から認証ユーザー資格情報をフローさせるための、RFC 8693トークン交換に準拠。

• スコープ付き資格情報: 実行コンテキストは、特定の呼び出し元IDに制限されて実行されます。

ランタイムセキュリティグリッド

環境変数

パッケージ環境変数

継承された agent-utilities 変数（すべてのコネクタに適用）

20 パッケージ変数 + 16 継承変数。.env.example と共有 agent-utilities セットから自動生成 — 編集しないでください。

サーバーが読み取るすべての変数。コピー＆ペースト用の出発点として .env.example を参照してください。

SearXNG 接続

MCPサーバー / トランスポート

テレメトリとガバナンス

インストール

実行したい内容に一致するエクストラを選択してください：

# Connector-focused MCP server (includes the shared graph engine)
uv pip install "searxng-mcp[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)
uv pip install "searxng-mcp[agent]"

# Everything (development)
uv pip install "searxng-mcp[all]"      # or: python -m pip install "searxng-mcp[all]"

コンテナイメージ（:mcp と :agent）

1つのマルチステージdocker/Dockerfileが、--targetで選択される2つの適切なサイズのイメージを構築します：

docker build --target mcp   -t example/searxng-mcp:mcp    docker/   # connector-focused MCP server
docker build --target agent -t example/searxng-mcp:agent-local docker/   # agent runtime

docker/mcp.compose.ymlはコネクタ中心の:mcpサーバーを実行し、docker/agent.compose.ymlは エージェント（immutable agent digest）を、同じ場所に配置された:mcpサイドカーとともに実行します。

知識グラフデータベース（epistemic-graph）

[mcp]と[agent]の両方が、必須のAgent Utilitiesコア依存関係（epistemic-graph[full]）を通じてepistemic-graphエンジンを搭載しています。[mcp]エクストラは サーバーをコネクタ中心に保ち、[agent]はさらにモデルオーケストレーションを有効にします。ローカル デプロイメントではバンドルされたエンジンを使用できます。本番環境や共有状態の場合は、 epistemic-graphを専用のデータベースサービスとして実行し、ランタイムがそれを使用するように設定してください。 デプロイメントレシピ（シングルノード + Raft HA）、接続設定、アーキテクチャ 図は、 epistemic-graphデプロイメントガイドに文書化されています。

ドキュメント

完全なドキュメントは 公式ドキュメントサイトとして公開されており、 インストール、デプロイ、日常運用の推奨リファレンスです。

AGENTS.mdは正規のコントリビューター/エージェント向けガイダンスです。

リポジトリオーナー

コントリビュート

コントリビューションを歓迎します！プルリクエストを提出する前に、ローカルチェックを実行してコード品質を確保してください：

• ruff format .でコードをフォーマット

• ruff check .でコードをリント

• mypy .で型安全性を検証

• pytestでテストスイートを実行

agent-utilities-deploymentでデプロイ

このパッケージを統合された**agent-utilities-deployment** ワークフローでプロビジョニングします。インストール済みパッケージ、編集可能なソース、またはイミュータブルコンテナの パスを選択し、AgentConfigにはランタイムのシークレットとTLSプロファイル参照のみを記録し、 ドクター、登録、ポリシー、オブザーバビリティ、ロールバックのゲートを実行します。エージェントに "agent-utilities-deploymentでsearxng-mcpをデプロイ" と依頼してください。

リポジトリにはデプロイプロファイル、資格情報値、証明書パス、または 環境固有のエンドポイントは埋め込まれていません。これらはランタイムにAgentConfigと 設定されたシークレットプロバイダーを通じて提供してください。

ガバナンス対象の機能契約

このパッケージは、専門的な手順を参照ワークフローとして保持した、コンパクトな正規のスキルサーフェスを提供します。現在のMCPツール、スキルメタデータ、 connector_manifest.yml、オントロジー、マッピング、シェイプ、フィクスチャ、マイグレーション、 ツールスキーマフィンガープリント、および認証メタデータは、1つのバージョン管理された 機能契約を形成します。これらを一緒に検証してください。古いツール名や 過去のタスク別スキルラッパーに依存しないでください。

ランタイムエンドポイント、認証情報、証明書の信頼、テナントのID、保持期間、 および可観測性ポリシーはデプロイメント入力であり、パッケージ化された値になることはありません。 構成、信頼、プライバシー を有効にする前に、ネットワークトランスポート、コネクタの取り込み、GraphOS 委任、またはトレースのエクスポートを参照してください。