Skip to content
Back to search

ask-search

SkillWorks with Claude CodeGitHub

"Web search via self-hosted SearxNG. Aggregates Google, Bing, DuckDuckGo, Brave. Returns title/url/snippet. Zero API key required. Optional Tavily backend via SEARCH_PROVIDER=tavily."

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ythx-101--ask-search/badge.svg)](/listings/ythx-101--ask-search)

HTML

<a href="/listings/ythx-101--ask-search"><img src="/api/listings/ythx-101--ask-search/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**1. Start SearxNG** (Docker Compose, recommended)

git clone https://github.com/ythx-101/ask-search
cd ask-search/searxng
cp .env.example .env      # then set SEARXNG_SECRET (python3 -c "import secrets; print(secrets.token_hex(32))")
docker compose up -d

Or with plain `docker run`:

docker run -d --name searxng \
  -p 127.0.0.1:8080:8080 \
  -e SEARXNG_SECRET=your-secret-key \
  -v "$PWD/searxng/searxng.yml:/etc/searxng/settings.yml" \
  searxng/searxng

**2. Install the command**

bash install.sh              # or: sudo bash install.sh, or: bash install.sh ~/.local/bin

**3. Search**

ask-search "hello world"

Already have SearxNG?

git clone https://github.com/ythx-101/ask-search
cd ask-search
bash install.sh
export SEARXNG_URL=http://localhost:8080   # if not the default
ask-search "hello world"

Your SearxNG must have `json` enabled in `search.formats` in `settings.yml`:

search:
  formats:
    - html
    - json

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 46 lines
  1. ---
  2. name: ask-search
  3. description: "Web search via self-hosted SearxNG. Aggregates Google, Bing, DuckDuckGo, Brave. Returns title/url/snippet. Zero API key required. Optional Tavily backend via SEARCH_PROVIDER=tavily."
  4. ---
  5. # ask-search
  6. Web search powered by [SearxNG](https://github.com/searxng/searxng). Aggregates multiple search engines, no API key needed (optional Tavily backend).
  7. ## Usage
  8. ```bash
  9. ask-search "your query" # top 10 results
  10. ask-search "query" --num 5 # limit results
  11. ask-search "AI news" --categories news # news only
  12. ask-search "query" --lang zh-CN # Chinese results
  13. ask-search "query" --urls-only # URL list (pipe to web_fetch)
  14. ask-search "query" --json # raw JSON
  15. ```
  16. ## Agent Workflow
  17. 1. Run `ask-search "topic"` to get candidates
  18. 2. Check snippet — if enough, answer directly
  19. 3. If snippet truncated, use `web_fetch` on the URL for full content
  20. ## Parameters
  21. | Flag | Short | Description |
  22. |------|-------|-------------|
  23. | `--num N` | `-n` | Max results (default 10) |
  24. | `--engines` | `-e` | google,bing,duckduckgo,brave |
  25. | `--lang` | `-l` | zh-CN, en, ja, ko |
  26. | `--categories` | `-c` | general,news,images,science |
  27. | `--json` | `-j` | Raw JSON output |
  28. | `--urls-only` | `-u` | URLs only |
  29. ## Setup
  30. Requires SearxNG running locally, with `json` in `search.formats` (the bundled `searxng/` Docker Compose setup does this). Set `SEARXNG_URL` if not on default port 8080.
  31. ```bash
  32. bash install.sh # installs the `ask-search` command (sudo, or: bash install.sh ~/.local/bin)
  33. ```
  34. Optional Tavily backend: `SEARCH_PROVIDER=tavily` + `TAVILY_API_KEY` (`--engines/--lang/--categories` are ignored in this mode).
README.md · README · 384 lines
  1. <div align="center">
  2. # 🔍 ask-search
  3. **Self-hosted web search for AI agents — no search API key needed**
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  5. [![OpenClaw](https://img.shields.io/badge/OpenClaw-Skill-blue.svg)](https://github.com/openclaw/openclaw)
  6. [![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)](https://python.org)
  7. *Works in OpenClaw · Claude Code · Antigravity · Any CLI*
  8. </div>
  9. ask-search is a self-hosted web search CLI and MCP server for AI agents. It wraps SearxNG so Claude Code, OpenClaw, Antigravity or any shell can search Google, Bing, DuckDuckGo, Brave and more without a paid search API key. Tavily is an optional backend.
  10. 给 AI Agent 用的自托管联网搜索:包装 SearxNG,一条命令 / 一个 MCP server 就能聚合 Google、Bing、DuckDuckGo、Brave 等搜索结果,无需付费搜索 API key。
  11. Python: CLI 3.8+; MCP server 3.10+ (required by the `mcp` package).
  12. ---
  13. ## 😡 The Problem
  14. Your AI agent wants to search the web, but:
  15. - Most search APIs need a key, cost money, and are rate limited
  16. - Built-in web search sends your queries to third-party services
  17. **You just want your local agent to search Google and friends without a paid API.**
  18. ## ✅ The Solution
  19. `ask-search` wraps [SearxNG](https://github.com/searxng/searxng) — a self-hosted meta search engine that aggregates Google, Bing, DuckDuckGo, Brave and many more sources. One command, all results, no per-query fees.
  20. ```bash
  21. ask-search "Claude Code vs Cursor 2026"
  22. ```
  23. ```
  24. [1] Example result title
  25. https://example.com/article-1
  26. Example snippet text...
  27. [google,brave]
  28. [2] Another example result title
  29. https://example.com/article-2
  30. ...
  31. ```
  32. *(illustrative output)*
  33. ## 📊 Compatibility
  34. | Environment | Integration | Status |
  35. |-------------|-------------|--------|
  36. | **OpenClaw** | CLI Skill (`SKILL.md`) | ✅ |
  37. | **Claude Code** | CLI command | ✅ |
  38. | **Antigravity** | MCP Server | ✅ |
  39. | Any shell | `ask-search` CLI | ✅ |
  40. ## 🚀 Quick Start
  41. **1. Start SearxNG** (Docker Compose, recommended)
  42. ```bash
  43. git clone https://github.com/ythx-101/ask-search
  44. cd ask-search/searxng
  45. cp .env.example .env # then set SEARXNG_SECRET (python3 -c "import secrets; print(secrets.token_hex(32))")
  46. docker compose up -d
  47. ```
  48. Or with plain `docker run`:
  49. ```bash
  50. docker run -d --name searxng \
  51. -p 127.0.0.1:8080:8080 \
  52. -e SEARXNG_SECRET=your-secret-key \
  53. -v "$PWD/searxng/searxng.yml:/etc/searxng/settings.yml" \
  54. searxng/searxng
  55. ```
  56. **2. Install the command**
  57. ```bash
  58. bash install.sh # or: sudo bash install.sh, or: bash install.sh ~/.local/bin
  59. ```
  60. **3. Search**
  61. ```bash
  62. ask-search "hello world"
  63. ```
  64. ### Already have SearxNG?
  65. ```bash
  66. git clone https://github.com/ythx-101/ask-search
  67. cd ask-search
  68. bash install.sh
  69. export SEARXNG_URL=http://localhost:8080 # if not the default
  70. ask-search "hello world"
  71. ```
  72. Your SearxNG must have `json` enabled in `search.formats` in `settings.yml`:
  73. ```yaml
  74. search:
  75. formats:
  76. - html
  77. - json
  78. ```
  79. ## 🔧 Usage
  80. ```bash
  81. ask-search "query" # top 10 results
  82. ask-search "query" --num 5 # limit results
  83. ask-search "AI news" --categories news # news only
  84. ask-search "query" --lang zh-CN # language filter
  85. ask-search "query" --urls-only # URLs only (pipe to web_fetch)
  86. ask-search "query" --json # raw JSON
  87. ask-search "query" -e google,brave # specific engines
  88. ```
  89. ## ⚙️ Configuration
  90. | Variable | Default | Description |
  91. |----------|---------|-------------|
  92. | `SEARXNG_URL` | `http://localhost:8080` | SearxNG endpoint |
  93. | `SEARCH_PROVIDER` | `searxng` | Search backend: `searxng` or `tavily` |
  94. | `TAVILY_API_KEY` | *(none)* | Tavily API key (required when `SEARCH_PROVIDER=tavily`) — get one at [app.tavily.com](https://app.tavily.com) |
  95. ```bash
  96. # SearxNG (default)
  97. export SEARXNG_URL="http://localhost:8080"
  98. ask-search "query"
  99. # Tavily (opt-in)
  100. export SEARCH_PROVIDER=tavily
  101. export TAVILY_API_KEY=tvly-YOUR_API_KEY
  102. ask-search "query"
  103. ```
  104. ## 🤖 MCP Integration (Antigravity / Claude Code)
  105. ```json
  106. {
  107. "mcpServers": {
  108. "ask-search": {
  109. "command": "python3",
  110. "args": ["/path/to/ask-search/mcp/server.py"],
  111. "env": {
  112. "SEARXNG_URL": "http://localhost:8080",
  113. "TAVILY_API_KEY": "tvly-YOUR_API_KEY"
  114. }
  115. }
  116. }
  117. }
  118. ```
  119. Requires Python 3.10+ and `pip install mcp`.
  120. Claude Code one-liner:
  121. ```bash
  122. claude mcp add ask-search -e SEARXNG_URL=http://localhost:8080 -- python3 /path/to/ask-search/mcp/server.py
  123. ```
  124. MCP tools provided:
  125. - `web_search` — search via SearxNG
  126. - `web_search_news` — news search via SearxNG
  127. - `web_search_tavily` — search via Tavily API (requires `TAVILY_API_KEY`)
  128. ## 🦞 OpenClaw Skill
  129. Copy `SKILL.md` to your OpenClaw skills directory, or:
  130. ```bash
  131. # OpenClaw skill loader
  132. skill-add https://github.com/ythx-101/ask-search
  133. ```
  134. Then in OpenClaw:
  135. ```
  136. ask-search "latest news about X"
  137. ```
  138. ## 🤝 Agent Workflow
  139. ```bash
  140. # 1. Search
  141. ask-search "React Server Components performance 2026" --num 10
  142. # 2. Got a promising URL? Deep-dive:
  143. # Pass the URL to web_fetch / curl for full content
  144. # 3. News mode
  145. ask-search "GPT-5 release" --categories news --lang en
  146. ```
  147. ## 📁 Structure
  148. ```
  149. ask-search/
  150. ├── scripts/
  151. │ └── core.py # Main logic, CLI entry point
  152. ├── mcp/
  153. │ └── server.py # MCP server for AG/CC integration
  154. ├── searxng/ # Docker Compose + settings.yml for SearxNG
  155. ├── tests/ # unit tests (stdlib unittest, no network)
  156. ├── install.sh # Installer
  157. ├── SKILL.md # OpenClaw skill descriptor
  158. ├── llms.txt # Summary for LLM crawlers
  159. └── README.md
  160. ```
  161. ## ⚠️ SearxNG Setup Notes
  162. - Must enable `json` in `search.formats` in `settings.yml`
  163. - Bot detection may block requests from some IPs — add your server IP to `pass_ip` in `limiter.toml`
  164. - Bind to `127.0.0.1` for security unless you need remote access
  165. ## 🧭 When to use
  166. | Option | API key | Self-hosted | Notes |
  167. |---|---|---|---|
  168. | ask-search + SearxNG | No | Yes | You maintain a SearxNG container |
  169. | ask-search + Tavily | Yes (Tavily) | No | Use when you don't want to run SearxNG |
  170. | Commercial search APIs | Yes | No | Pay-per-use |
  171. | Built-in agent web search | Depends on platform | No | Queries go through the platform provider |
  172. | Perplexica | No | Yes | Full AI search app with a UI; ask-search is a minimal CLI take on the same idea |
  173. Privacy note: no third-party search API sees your queries; SearxNG forwards them to upstream engines from your own server.
  174. ## ❓ FAQ
  175. **Does ask-search need an API key?**
  176. Not in the default SearxNG mode. In Tavily mode (`SEARCH_PROVIDER=tavily`) you need `TAVILY_API_KEY`.
  177. **How do I use it in Claude Code?**
  178. Call the CLI from Bash (`ask-search "query"`), or register the MCP server (see MCP Integration above).
  179. **Why do I get 403 or "SearxNG did not return JSON"?**
  180. `json` must be listed in `search.formats` in SearxNG's `settings.yml` (the bundled `searxng/searxng.yml` does this). If requests are blocked by the bot limiter, add your IP to `pass_ip` in `limiter.toml`.
  181. **Is it really private?**
  182. No third-party search API sees your queries, but SearxNG still forwards them to upstream engines (Google, Bing, etc.) from your own server's IP.
  183. **How do I search in Chinese or get news only?**
  184. `ask-search "query" --lang zh-CN` and `ask-search "query" --categories news`.
  185. **Can I use Tavily instead of SearxNG?**
  186. Yes: `export SEARCH_PROVIDER=tavily TAVILY_API_KEY=tvly-YOUR_API_KEY`, and install `tavily-python` (`pip install tavily-python`; `install.sh` does this automatically when `TAVILY_API_KEY` is set). In Tavily mode `--engines`, `--lang` and `--categories` are ignored.
  187. **Does it work on Windows?**
  188. It needs Python 3 and curl; `install.sh` is a bash script, so on Windows use WSL. Not tested on native Windows.
  189. **How is it different from Perplexica?**
  190. Perplexica is a full AI search application with a UI. ask-search only returns search results (title, URL, snippet) for an agent to consume, via one CLI command or an MCP server.
  191. ## 中文说明
  192. **ask-search** 是给 AI Agent 用的自托管联网搜索工具:包装 SearxNG 元搜索引擎,聚合 Google、Bing、DuckDuckGo、Brave 等结果,无需 API Key(也可选用 Tavily)。支持 Claude Code 搜索、OpenClaw 技能和 MCP 搜索服务器。
  193. 快速开始:
  194. 1. `cd searxng && cp .env.example .env && docker compose up -d` 启动 SearxNG
  195. 2. `bash install.sh` 安装命令
  196. 3. `ask-search "你好" --lang zh-CN`
  197. ## 🌐 Deep-Dive Limitations & Workarounds
  198. `ask-search` returns URLs + snippets from search engine indexes. When your agent needs the **full page content** (deep-dive via `curl` / `web_fetch`), some sites will block depending on your server's network environment:
  199. ### What works out of the box
  200. | Site | Search (SearxNG) | Deep-dive (curl/fetch) | Why |
  201. |------|:-:|:-:|-----|
  202. | Most sites | ✅ | ✅ | No aggressive anti-bot |
  203. | Reddit | ✅ | ❌ VPS IP blocked | Reddit blocks datacenter IPs |
  204. | Zhihu (知乎) | ✅ | ❌ Login wall + fingerprint | Requires browser JS + login |
  205. | Medium | ✅ | ⚠️ Paywall | Partial content only |
  206. **Key insight**: Search always works because SearxNG queries search engines (Google, Brave, etc.), not the target sites directly. The search engines have already indexed the content. The problem only appears when your agent tries to fetch the full page.
  207. ### Solution 1: SOCKS proxy via residential IP
  208. If you have a machine on a residential network (home server, laptop, etc.), create an SSH SOCKS tunnel:
  209. ```bash
  210. # On your VPS/server:
  211. ssh -f -N -D 127.0.0.1:1082 user@your-home-machine
  212. # Then fetch through the proxy:
  213. curl -x socks5h://127.0.0.1:1082 "https://reddit.com/r/example/comments/xxx.json"
  214. ```
  215. For Reddit specifically, append `.json` to any post URL for structured data:
  216. ```bash
  217. # Returns full post + all comments as JSON
  218. curl -x socks5h://127.0.0.1:1082 \
  219. "https://www.reddit.com/r/LocalLLaMA/comments/xxxxx/post_title.json"
  220. ```
  221. To persist the tunnel as a systemd service:
  222. ```ini
  223. # /etc/systemd/system/socks-proxy.service
  224. [Unit]
  225. Description=SSH SOCKS Proxy for web scraping
  226. After=network.target
  227. [Service]
  228. Type=simple
  229. ExecStart=/usr/bin/ssh -N -D 127.0.0.1:1082 -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -o ExitOnForwardFailure=yes user@your-home-machine
  230. Restart=always
  231. RestartSec=10
  232. [Install]
  233. WantedBy=multi-user.target
  234. ```
  235. ### Solution 2: Headless browser for JS-heavy sites
  236. Sites like Zhihu require full browser rendering. Use Playwright with the SOCKS proxy:
  237. ```python
  238. from playwright.sync_api import sync_playwright
  239. with sync_playwright() as p:
  240. browser = p.chromium.launch(
  241. headless=True,
  242. proxy={"server": "socks5://127.0.0.1:1082"}
  243. )
  244. page = browser.new_page()
  245. page.goto("https://example.com/article")
  246. content = page.inner_text("article")
  247. ```
  248. > **Note**: Some sites (Zhihu, etc.) detect headless browsers even through proxies. For these, you may need a real browser session with login cookies, or delegate the fetch to an agent running on a local machine (e.g., Claude Code on a Mac).
  249. ### Solution 3: Leverage archive caches
  250. When direct access fails, try archived versions:
  251. ```bash
  252. # Archive.org (works surprisingly often for Reddit)
  253. curl "https://web.archive.org/web/2026/https://reddit.com/r/example/comments/xxx"
  254. ```
  255. ### Solution 4: Multi-node agent architecture
  256. If you run agents on multiple machines (e.g., OpenClaw on VPS + Claude Code on local Mac):
  257. ```
  258. VPS agent: ask-search "query" → gets URLs + snippets
  259. ↓
  260. Local agent: web_fetch(url) → full content (residential IP, no blocks)
  261. ↓
  262. VPS agent: receives full text, analyzes, responds
  263. ```
  264. This is the most robust approach — search on your server, deep-dive from a local machine where anti-bot measures don't apply.
  265. ### TL;DR
  266. | Problem | Fix |
  267. |---------|-----|
  268. | Reddit blocks your IP | SSH SOCKS proxy + `.json` API |
  269. | Site needs JS rendering | Playwright + proxy |
  270. | Site needs login (Zhihu) | Delegate to local agent or use logged-in browser |
  271. | Everything blocked | Fall back to search snippets + archive caches |
  272. ## 🤝 Contributing
  273. Issues and PRs welcome.
  274. ## Acknowledgements
  275. Inspired by [Perplexica](https://github.com/ItzCrazyKns/Perplexica) —
  276. the idea of using self-hosted SearxNG as a private search backend comes from there.
  277. ask-search strips it down to a single CLI command for agent use.
  278. ## 📄 License
  279. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.