Searchgirl documentation

Searchgirl has four faces served by the same binary. This page walks through each one, the SearXNG engine underneath, and the suite (federated) mode.

The web UI

http://localhost:8089 — a home with suggestions, results by category (General, News, Images, Videos, Science, IT and more), language/date/SafeSearch filters, direct answers and infoboxes, and a light/dark theme. Thumbnails pass through Searchgirl’s own proxy (/thumb): your browser never touches the engines’ hosts.

The REST API

Endpoint	What it does
GET /api/search?q=...	Search. Params: category, language, time_range (day/week/month/year), safesearch (0-2), page, engines.
GET /api/suggest?q=...	Autocomplete.
POST /api/answer	AI synthesis with citations: {"query": "...", "fetch_pages": true} — 503 without an LLM.
POST /api/read	URL → Markdown: {"url": "https://..."}.
GET /api/engines · /api/categories	Engine/category catalog.
GET /api/config	Version, auth mode, LLM availability.
GET /healthz	Liveness.

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

The response is a normalized, stable shape — dedup by URL, score, domain, ISO dates — independent of SearXNG’s raw JSON.

MCP (for Claude Code, Claude Desktop or any MCP client)

The MCP server runs at http://localhost:8089/mcp (streamable HTTP transport). Tools:

• search — metasearch with category, language, time_range, max_results.
• url_read — fetches a public URL as Markdown (with an SSRF guard).
• answer — search + synthesis with [n] citations (only appears if an LLM is configured).

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

If you set SEARCHGIRL_MCP_TOKEN, add the header:

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

Prefer stdio? The same binary: searchgirl serve (without -http) speaks MCP over stdio — it needs to reach SearXNG (uncomment the 127.0.0.1:8090:8080 mapping in the compose and export SEARXNG_URL=http://localhost:8090). For day-to-day use, the HTTP /mcp is the recommended path.

AI Answer (optional, off by default)

With a model configured, the AI Answer button appears in the UI, along with POST /api/answer and the answer MCP tool: it searches, takes the best sources and writes a short answer citing [1][2], with the source list at the foot. Without a model, everything else works unchanged.

# 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 under the hood

The engine’s config lives in searxng/settings.yml:

• search.formats: [html, json] — essential: without json the API returns 403.
• server.limiter: false — SearXNG is not exposed; Searchgirl provides the rate limiting.
• autocomplete: duckduckgo — enables /api/suggest.

SearXNG ships with roughly 200 engines active by default. To curate them, add to settings.yml:

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

and docker compose restart searxng.

Auth, tokens and rate limiting

• Local login — one user (SEARCHGIRL_USER/SEARCHGIRL_PASS), the standard Escriba screen; everything is gated until sign-in.
• Bearer tokens — SEARCHGIRL_MCP_TOKEN accepts several named tokens (claude:abc...,n8n:def...); revoking one is removing it from the list, without rotating the rest. Tokens compose with both local login and federation — humans sign in, agents use the token.
• Rate limiting — per-IP on API, MCP and login (SEARCHGIRL_RATE_RPS / SEARCHGIRL_RATE_BURST). Behind a reverse proxy, set SEARCHGIRL_TRUSTED_PROXIES so the limit sees the real client IP via X-Forwarded-For.

Suite mode (federated with Lockatus)

In the Escriba Suite’s docker-compose.suite.yml, Searchgirl joins on port 8089 with AUTH_MODE=federado: single sign-on via Lockatus (PKCE S256, HMAC cookie), no local login. Access is governed from the hub’s matrix (roles admin/usuario). For a production SSO deployment — registering the searchgirl client, the exact redirect_uri rules and verification — see the federation section of DEPLOY.md.

Note

The full detail — every environment variable, panel-by-panel deployment, troubleshooting tables and the security model — lives in the repo’s README and DEPLOY.md.

View on GitHub