Searchgirlドキュメント

Searchgirlには、同じバイナリが提供する4つの顔があります。このページでは、それぞれの顔、その下で動くSearXNGエンジン、そしてスイート（連携）モードを順に解説します。

Web UI

http://localhost:8089 — サジェスト付きのホーム、カテゴリ別の結果（一般、ニュース、画像、動画、科学、ITほか）、言語 / 日付 / SafeSearchのフィルター、ダイレクトアンサーとインフォボックス、ライト / ダークテーマ。サムネイルはSearchgirl自身のプロキシ（/thumb）を通ります： ブラウザがエンジンのホストに触れることは決してありません。

REST API

エンドポイント	役割
`GET /api/search?q=...`	検索。パラメータ：`category`、`language`、`time_range`（day/week/month/year）、`safesearch`（0-2）、`page`、`engines`。
`GET /api/suggest?q=...`	オートコンプリート。
`POST /api/answer`	引用付きAI合成：`{"query": "...", "fetch_pages": true}` — LLMがない場合は503。
`POST /api/read`	URL → Markdown：`{"url": "https://..."}`。
`GET /api/engines` · `/api/categories`	エンジン / カテゴリのカタログ。
`GET /api/config`	バージョン、認証モード、LLMの利用可否。
`GET /healthz`	生存確認。

curl "http://localhost:8089/api/search?q=searxng&category=news&time_range=week"

レスポンスは正規化された安定した形状です — URLによる重複排除、スコア、ドメイン、ISO日付 — SearXNGの生のJSONには依存しません。

MCP（Claude Code、Claude Desktop、あらゆるMCPクライアント向け）

MCPサーバーは http://localhost:8089/mcp（ストリーマブルHTTPトランスポート）で動作します。ツール：

search — category、language、time_range、max_results を持つメタ検索。
url_read — 公開URLをMarkdownとして取得します（SSRFガード付き）。
answer — 検索 + [n] 引用付きの合成（LLMが設定されている場合のみ現れます）。

# Claude Code:
claude mcp add --transport http searchgirl http://localhost:8089/mcp

SEARCHGIRL_MCP_TOKEN を設定した場合は、ヘッダーを追加します：

claude mcp add --transport http searchgirl https://your-domain/mcp \
  --header "Authorization: Bearer <your token>"

stdioが好みですか？同じバイナリです：searchgirl serve（-http なし）はstdio経由のMCPを話します — SearXNGに到達できる必要があります（composeの 127.0.0.1:8090:8080 マッピングのコメントを外し、SEARXNG_URL=http://localhost:8090 をエクスポートします）。日常的な利用では、 HTTPの /mcp が推奨の経路です。

AI回答（オプション、既定ではオフ）

モデルを設定すると、UIに AI回答 ボタンが現れ、POST /api/answer とMCPツール answer も使えるようになります：検索し、最良のソースを取り、[1][2] を引用する短い回答を書き、末尾にソース一覧を添えます。モデルがなくても、それ以外はすべて変わらず動きます。

# Anthropic (native — takes priority if set):
ANTHROPIC_API_KEY=sk-ant-...

# or any OpenAI-compatible endpoint — local Ollama, OpenRouter, DeepSeek:
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_MODEL=deepseek/deepseek-chat
LLM_API_KEY=sk-or-...

内部で動くSearXNG

エンジンの設定は searxng/settings.yml にあります：

search.formats: [html, json] — 必須：json がないとAPIは403を返します。
server.limiter: false — SearXNGは公開されないため、レート制限はSearchgirlが担います。
autocomplete: duckduckgo — /api/suggest を有効化します。

SearXNGは既定でおよそ200のエンジンが有効な状態で出荷されます。取捨選択するには、settings.yml に追加します：

use_default_settings:
  engines:
    remove: [qwant, startpage]   # the ones that keep failing on you

そして docker compose restart searxng を実行します。

認証、トークン、レート制限

ローカルログイン — 単一ユーザー（SEARCHGIRL_USER/SEARCHGIRL_PASS）、Escribaの標準画面。サインインするまですべてがゲートされます。
Bearerトークン — SEARCHGIRL_MCP_TOKEN は複数の名前付きトークンを受け付けます（claude:abc...,n8n:def...）。1つの失効はリストからの削除であり、残りをローテーションしません。トークンはローカルログインとも連携とも組み合わせられます — 人間はサインインし、エージェントはトークンを使います。
レート制限 — API、MCP、ログインに対してIPごと（SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST）。リバースプロキシの背後では、制限が X-Forwarded-For 経由で実際のクライアントIPを見られるよう SEARCHGIRL_TRUSTED_PROXIES を設定します。

スイートモード（Lockatusとの連携）

Escribaスイートの docker-compose.suite.yml では、Searchgirlは AUTH_MODE=federado でポート 8089 に参加します：Lockatus経由のシングルサインオン（PKCE S256、HMACクッキー）、ローカルログインなし。アクセスはハブのマトリクス（ロール admin/usuario）から管理されます。本番のSSOデプロイ — searchgirl クライアントの登録、正確な redirect_uri のルール、検証 — については、DEPLOY.md の連携セクションを参照してください。

GitHubで見る