SearxNG MCP Server

SearxNG MCP サーバー

SearxNG を使用してウェブ検索機能を提供する Model Context Protocol（MCP）サーバーです。Claude などの AI アシスタントがウェブを検索できるようにします。

AI が人間の監督のもとで作成しました。人工知能にも、コーヒーブレイクの時間を教えてくれる人が必要なことがあります！ 🤖☕

概要

このプロジェクトは、プライバシーを尊重するメタ検索エンジンである SearxNG に接続する MCP サーバーを実装しています。このサーバーを使うと、ユーザーを追跡することなく、LLM がウェブを検索できます。

このサーバーは LLM 向けに特化して設計されており、コンテキストウィンドウの使用量を最小限に抑えるため、必須の機能のみを備えています。この合理化されたアプローチにより、LLM と検索エンジン間の効率的な通信を実現し、より重要な情報のために貴重なコンテキスト領域を確保できます。

特長

• SearxNG によるプライバシー重視のウェブ検索
• LLM 連携のためのシンプルな API
• Claude Desktop やその他の MCP 対応クライアントと互換性があります
• 検索パラメーターを設定可能
• LLM 向けに最適化された、整形済みのすっきりした検索結果

MCP 対応アプリケーションとの連携

連携例

pipx run を使用する（推奨、インストール不要）

ホームディレクトリに .clauderc ファイルを作成します。

{
  "mcpServers": {
    "searxng": {
      "command": "pipx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

uvx run を使用する（インストール不要）

{
  "mcpServers": {
    "searxng": {
      "command": "uvx",
      "args": [
        "run", "searxng-simple-mcp@latest"
      ],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

pip を使って Python で実行する（インストールが必要）

{
  "mcpServers": {
    "searxng": {
      "command": "python",
      "args": ["-m", "searxng_simple_mcp.server"],
      "env": {
        "SEARXNG_MCP_SEARXNG_URL": "https://your-instance.example.com"
      }
    }
  }
}

Docker を使って実行する（インストール不要）

{
  "mcpServers": {
    "searxng": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", "--network=host",
        "-e", "SEARXNG_MCP_SEARXNG_URL=http://localhost:8080",
        "ghcr.io/sacode/searxng-simple-mcp:latest"
      ]
    }
  }
}

注： MCP サーバーで Docker を使用する場合：

1. env オブジェクトは Docker コンテナに正しく渡されないため、環境変数は args 配列内の -e フラグを使って直接渡す必要があります。
2. localhost で実行中の SearxNG インスタンス（例：http://localhost:8080）にアクセスする必要がある場合は、コンテナからホストのネットワークにアクセスできるように、--network=host フラグを使用してください。そうしないと、コンテナ内の「localhost」はホストマシンではなく、コンテナ自体を指します。
3. --network=host を使用する場合、コンテナはホストのネットワークスタックを直接共有するため、ポートマッピング（-p）は不要であり、無視されます。

設定

環境変数を使ってサーバーを設定します。

環境変数	説明	デフォルト値
SEARXNG_MCP_SEARXNG_URL	使用する SearxNG インスタンスの URL	https://paulgo.io/
SEARXNG_MCP_TIMEOUT	HTTP リクエストのタイムアウト時間（秒）	10
SEARXNG_MCP_DEFAULT_RESULT_COUNT	返す結果のデフォルト件数	10
SEARXNG_MCP_DEFAULT_LANGUAGE	結果の言語コード（例：'en'、'ru'、'all'）	all
SEARXNG_MCP_DEFAULT_FORMAT	結果のデフォルト形式（'text'、'json'）	text
SEARXNG_MCP_LOG_LEVEL	ログレベル（例：'DEBUG'、'INFO'、'WARNING'、'ERROR'、'CRITICAL'）	ERROR
TRANSPORT_PROTOCOL	トランスポートプロトコル（'stdio' または 'sse'）	stdio

注： ERROR より上位のログレベル（DEBUG や INFO など）を設定すると、通信チャネルへの出力が過剰になり、一部のアプリケーションとの連携が機能しなくなることがあります。

独自のインスタンスをホストせずに利用したい場合は、https://searx.space で公開されている SearxNG インスタンスの一覧を確認できます。

インストールと使用方法

前提条件

• Python 3.10 以降
• SearxNG インスタンス（公開またはセルフホスト）

オプション 1：インストールせずに実行する（推奨）

このサーバーを使う最も簡単な方法は pipx または uvx を使用することです。パッケージを恒久的にインストールせずに実行できます。

# Using pipx
pip install pipx  # Install pipx if you don't have it
pipx run searxng-simple-mcp

# OR using uvx
pip install uvx  # Install uvx if you don't have it
uvx run searxng-simple-mcp

設定オプションを直接渡すこともできます。

# Using pipx with custom SearxNG instance
pipx run searxng-simple-mcp --searxng-url https://your-instance.example.com

オプション 2：PyPI またはソースからインストールする

恒久的にインストールする場合：

# From PyPI using pip
pip install searxng-simple-mcp

# OR using uv (faster installation)
pip install uv
uv pip install searxng-simple-mcp

# OR from source
git clone https://github.com/Sacode/searxng-simple-mcp.git
cd searxng-simple-mcp
pip install uv
uv pip install -e .

インストール後、次のコマンドでサーバーを実行できます。

# Run directly after installation
python -m searxng_simple_mcp.server

# OR with configuration options
python -m searxng_simple_mcp.server --searxng-url https://your-instance.example.com

オプション 3：Docker

Docker の使用を希望する場合：

# Pull the Docker image
docker pull ghcr.io/sacode/searxng-simple-mcp:latest

# Run the container with default settings (stdio transport)
docker run --rm -i ghcr.io/sacode/searxng-simple-mcp:latest

# Run with environment file for configuration
docker run --rm -i --env-file .env ghcr.io/sacode/searxng-simple-mcp:latest

# Run with SSE transport (starts HTTP server on port 8000)
docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse ghcr.io/sacode/searxng-simple-mcp:latest

# Building locally
docker build -t searxng-simple-mcp:local .
docker run --rm -i searxng-simple-mcp:local

# Using Docker Compose
docker-compose up -d

Docker の使用方法について詳しくは、以下のDocker の設定セクションを参照してください。

トランスポートプロトコル

MCP サーバーは、次の 2 つのトランスポートプロトコルをサポートしています。

• STDIO（デフォルト）：CLI アプリケーションや直接統合向け

  • すべての例でデフォルトで使用されます
  • Claude Desktop やその他の MCP 準拠クライアントとの統合に適しています
  • HTTP サーバーは起動しません

• SSE（Server-Sent Events）：ウェブベースのクライアントや HTTP ベースの統合向け

  • クライアントが接続できる HTTP サーバーを起動します
  • リアルタイム更新が必要なウェブアプリケーションやサービスに便利です
  • Docker を使用する場合はポートマッピングが必要です

SSE トランスポートの使用

SSE トランスポートプロトコルを使用するには、次の手順に従います。

1. 直接実行する場合：

   # Set the transport protocol to SSE
   TRANSPORT_PROTOCOL=sse python -m searxng_simple_mcp.server
   
   # Or with FastMCP
   fastmcp run src/searxng_simple_mcp/server.py --transport sse
   

2. Docker を使用する場合：

   # Run with SSE transport protocol
   docker run -p 8000:8000 -e TRANSPORT_PROTOCOL=sse -e SEARXNG_MCP_SEARXNG_URL=https://your-instance.example.com ghcr.io/sacode/searxng-simple-mcp:latest
   

3. Docker Compose を使用する場合（同梱の docker-compose.yml を使用）：

   environment:
     - SEARXNG_MCP_SEARXNG_URL=https://searx.info
     - SEARXNG_MCP_TIMEOUT=10
     - SEARXNG_MCP_MAX_RESULTS=20
     - SEARXNG_MCP_LANGUAGE=all
     - TRANSPORT_PROTOCOL=sse # Transport protocol: stdio or sse
   

SSE を使用すると、デフォルトでは http://localhost:8000 の HTTP 経由でサーバーにアクセスできます。

MCP クライアントから SSE サーバーに接続するには、次のような設定を使用します。

{
  "mcpServers": {
    "searxng": {
      "url": "http://localhost:8000",
      "transport": "sse"
    }
  }
}

注： すべてのアプリケーションが SSE トランスポートプロトコルをサポートしているわけではありません。このトランスポート方式を使用する前に、MCP クライアントが SSE に対応していることを確認してください。

開発

開発とテストには、次のコマンドを使用します。

# Install dependencies
uv pip install -e .

# Run linter and formatter
ruff check .
ruff check --fix .
ruff format .

# Run the server directly
python -m src.searxng_simple_mcp.server

# OR using FastMCP
fastmcp run src/searxng_simple_mcp/server.py  # Use stdio transport (default)
fastmcp run src/searxng_simple_mcp/server.py --transport sse  # Use sse transport

# Run in development mode (launches MCP Inspector)
fastmcp dev src/searxng_simple_mcp/server.py

PyPI への公開

パッケージの新しいバージョンを PyPI に公開するメンテナー向けの手順です。

# Install development dependencies
npm run install:deps

# Clean, build, and check the package
npm run build:package
npm run check:package

# Publish to PyPI (requires PyPI credentials)
npm run publish:pypi

# Alternatively, use the all-in-one commands to update version and publish
npm run publish:patch  # Increments patch version (1.0.1 -> 1.0.2)
npm run publish:minor  # Increments minor version (1.0.1 -> 1.1.0)
npm run publish:major  # Increments major version (1.0.1 -> 2.0.0)

これらのコマンドでは、次の処理を行います。

1. package.json と pyproject.toml の両方でバージョンを更新します
2. 古いビルドを削除するため、dist ディレクトリをクリーンアップします
3. パッケージをビルドします（wheel とソースディストリビューションを作成します）
4. パッケージにエラーがないか確認します
5. パッケージを PyPI にアップロードします

PyPI アカウントを用意し、twine で認証する必要があります。認証は、次の方法で設定できます。

• ホームディレクトリに .pypirc ファイルを作成する
• 環境変数（TWINE_USERNAME と TWINE_PASSWORD）を使用する
• PyPI API トークンを使用する（推奨）

Docker の設定

MCP サーバーで Docker を使用する場合は、次の点に注意してください。

1. MCP クライアントとの統合：Claude Desktop やその他の MCP 準拠クライアントと統合する場合は、Docker を使用する（インストール不要）セクションに記載された設定を使用してください。

2. トランスポートプロトコル：

   • デフォルトでは、Docker コンテナは stdio トランスポートプロトコルを使用します
   • SSE トランスポートについては、SSE トランスポートの使用セクションを参照してください

3. 設定オプション：

   • 環境ファイル（.env）を使用してサーバーを設定します：docker run --env-file .env ...
   • -e フラグを使って個別の環境変数を渡します：docker run -e SEARXNG_MCP_SEARXNG_URL=https://example.com ...
   • 使用可能な環境変数については、設定セクションを参照してください

4. ネットワーク：

   • ホストマシン上のサービスにアクセスする必要がある場合は、--network=host を使用します
   • SSE サーバーをネットワークに公開する場合は、-p 8000:8000 を使用します

パッケージ構成

searxng-simple-mcp/
├── src/
│   ├── run_server.py         # Entry point script
│   └── searxng_simple_mcp/   # Main package
├── docker-compose.yml        # Docker Compose configuration
├── Dockerfile                # Docker configuration
└── pyproject.toml            # Python project configuration

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細については LICENSE ファイルを参照してください。