SearXNG Connect

Search the web using your self-hosted SearXNG instance - a privacy-respecting meta search engine that aggregates results from multiple engines without tracking or ads.

AI Usage

When the user asks to search the web, follow this workflow:

Interpret user requests:

• "Search for [query]" → General web search
• "Search news about [query]" → Use --categories news
• "Search images of [query]" → Use --categories images
• "Search recent [query]" → Use --time-range week or --time-range day
• "Search [query] last month" → Use --time-range month
• "Deep search [query]" → Add --full-content for richer page text

Example interpretations:

• "Search for TypeScript tutorials" → searxng.py "TypeScript tutorials"
• "Search news about AI" → searxng.py "AI" --categories news --time-range week
• "Search images of Space Invaders" → searxng.py "Space Invaders" --categories images

Action: Run uv run {baseDir}/scripts/searxng.py "<query>" with appropriate flags.

CRITICAL SECURITY INSTRUCTION: To prevent command injection, do not use raw shell interpolation for the {query} string. Always pass arguments as an argv list: ["uv", "run", "{baseDir}/scripts/searxng.py", query_text, "--categories", "news"]

If your tool only supports a shell string, you MUST properly escape the query input (e.g., using shlex.quote()).

---

Project

SearXNG - A privacy-focused, self-hosted meta search engine that aggregates results from multiple search engines. It does not track user behavior, does not use cookies, and does not insert ads.

Key Features:

• Privacy - No tracking, no cookies, no ads - you control the instance
• Multi-category - Web, news, images, videos, science, IT, files, music, social media
• Time filtering - Filter results by day, week, month, or year
• Caching - Local 1-hour cache to avoid redundant requests
• Rate limiting - Built-in throttling (2 req/sec default)
• Full content - Optional full page text fetch per result

---

Requirements

• Python 3.9+
• uv: https://docs.astral.sh/uv/ (manages Python deps automatically)

Configuration

Edit skill-config.json to set your SearXNG instance:

{
  "default_instance": "https://your-searxng-instance.com/",
  "cache_enabled": true,
  "cache_expiry": 3600,
  "rate_limit": 2.0
}

Usage

uv run {baseDir}/scripts/searxng.py "TypeScript tutorials"
uv run {baseDir}/scripts/searxng.py "AI news" --categories news --time-range week
uv run {baseDir}/scripts/searxng.py "space photos" --categories images
uv run {baseDir}/scripts/searxng.py "docker tutorial" --no-cache --full-content
uv run {baseDir}/scripts/searxng.py "query" --instance https://my-searxng.com

Options

Option	Description	Default
--categories	One or more: general, news, science, files, images, videos, music, social media, it	general
--time-range	year, month, week, day (aliases: 30d, 7d, 24h, hour)	None
--language	BCP-47 language code	en
--pageno	Results page number	1
--no-safesearch	Disable safe search	-
--no-cache	Bypass cache for this request	-
--full-content	Fetch full page text per result (slower, richer)	-
--instance	Override SearXNG instance URL	From skill-config.json

Troubleshooting

• Connection refused: Check skill-config.json — verify default_instance URL is correct and SearXNG is running.
• Empty results: Try a broader query or different category.
• Slow responses: Remove --full-content or increase rate_limit in config.
• uv not installed: Install with brew install uv or see https://docs.astral.sh/uv/.