Skip to content
Back to search

searxng-ai-kit

Standalone SearXNG CLI for coding agents

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/nikvdp--searxng-ai-kit/badge.svg)](/listings/nikvdp--searxng-ai-kit)

HTML

<a href="/listings/nikvdp--searxng-ai-kit"><img src="/api/listings/nikvdp--searxng-ai-kit/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.

These steps run a script from the network that findsafeskills does not scan.

Download a Standalone Binary (Recommended)

The recommended install path is to download the pre-built binary for your platform from the [GitHub releases page](https://github.com/nikvdp/searxng-ai-kit/releases).

The source install path has to build and vendor a pinned SearXNG wheel before the CLI can run, so it is slower and more involved than a normal `uv tool install`. Use the binary unless you are developing the project or intentionally updating the pinned upstream SearXNG version.

Release binaries are currently published for Linux and macOS. Windows binaries are disabled for now because the current pybin Windows package launcher is not native yet.

After downloading, make the binary executable and put it somewhere on your `PATH`:

chmod +x searxng-ai-kit-*
./searxng-ai-kit-* --help

Install from Source with uv (Advanced)

Use this path when you want to develop the project, inspect the vendored SearXNG build, or update the pinned SearXNG commit.

Prerequisites: - Python 3.11+ - [uv](https://docs.astral.sh/uv/getting-started/installation/)

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone https://github.com/nikvdp/searxng-ai-kit
cd searxng-ai-kit

# Build the pinned SearXNG wheel and set up the local environment
uv run python dev-setup.py

# Install as a uv tool
uv tool install .

# Verify
searxng --help

Development Setup

# Clone and set up for development
git clone https://github.com/nikvdp/searxng-ai-kit
cd searxng-ai-kit

# Build SearXNG wheel, generate configs, sync dependencies
python dev-setup.py

# Test
uv run searxng search "test" --engines duckduckgo

The build system automatically: - Installs Python 3.11+ via uv - Builds SearXNG wheel with proper dependency isolation - Handles modern type annotations (`str | Exception`) - Generates local configuration files

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.

README.md · README · 799 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # SearXNG AI Kit
  2. **AI-powered search for your terminal, code, and AI assistants**
  3. An AI-enhanced command-line interface, Python library, and MCP server for the SearXNG privacy-respecting metasearch engine. Research topics with AI assistance, search the web from your terminal, integrate into Python projects, or connect AI assistants with support for 180+ search engines.
  4. ## Features
  5. 🔍 **CLI tool** - Search from your terminal with AI-enhanced research capabilities
  6. 🤖 **AI chat** - Ask questions and get comprehensive research using 180+ search engines
  7. 🐍 **Python library** - Programmatic search and AI-powered content retrieval
  8. 🔌 **MCP server** - AI assistant integration with advanced research tools
  9. 📦 **Standalone binaries** - Pre-built executables for Linux and macOS
  10. ## Installation
  11. ### Download a Standalone Binary (Recommended)
  12. The recommended install path is to download the pre-built binary for your
  13. platform from the
  14. [GitHub releases page](https://github.com/nikvdp/searxng-ai-kit/releases).
  15. The source install path has to build and vendor a pinned SearXNG wheel before
  16. the CLI can run, so it is slower and more involved than a normal `uv tool
  17. install`. Use the binary unless you are developing the project or intentionally
  18. updating the pinned upstream SearXNG version.
  19. Release binaries are currently published for Linux and macOS. Windows binaries
  20. are disabled for now because the current pybin Windows package launcher is not
  21. native yet.
  22. After downloading, make the binary executable and put it somewhere on your
  23. `PATH`:
  24. ```bash
  25. chmod +x searxng-ai-kit-*
  26. ./searxng-ai-kit-* --help
  27. ```
  28. ### Install with Nix
  29. ```bash
  30. nix profile install . # Install from this checkout
  31. nix run . -- engines --common # Run without installing
  32. nix build # Build ./result/bin/searxng
  33. ```
  34. Includes Python and runtime dependencies; uses the existing `setup.py` vendoring
  35. hooks with the pinned upstream SearXNG wheel. No first-run setup required.
  36. Both build paths pin upstream SearXNG `cff884f98b11` (2026-10-29). Upstream build
  37. failures abort packaging rather than shipping an older vendored copy. Search
  38. still depends on engine availability; CAPTCHAs and rate limits can block engines.
  39. `number_of_results` counts retrieved rows, before library/MCP result limits.
  40. ### Install from Source with uv (Advanced)
  41. Use this path when you want to develop the project, inspect the vendored SearXNG
  42. build, or update the pinned SearXNG commit.
  43. Prerequisites:
  44. - Python 3.11+
  45. - [uv](https://docs.astral.sh/uv/getting-started/installation/)
  46. ```bash
  47. # On macOS and Linux
  48. curl -LsSf https://astral.sh/uv/install.sh | sh
  49. git clone https://github.com/nikvdp/searxng-ai-kit
  50. cd searxng-ai-kit
  51. # Build the pinned SearXNG wheel and set up the local environment
  52. uv run python dev-setup.py
  53. # Install as a uv tool
  54. uv tool install .
  55. # Verify
  56. searxng --help
  57. ```
  58. ### Development Setup
  59. ```bash
  60. # Clone and set up for development
  61. git clone https://github.com/nikvdp/searxng-ai-kit
  62. cd searxng-ai-kit
  63. # Build SearXNG wheel, generate configs, sync dependencies
  64. python dev-setup.py
  65. # Test
  66. uv run searxng search "test" --engines duckduckgo
  67. ```
  68. The build system automatically:
  69. - Installs Python 3.11+ via uv
  70. - Builds SearXNG wheel with proper dependency isolation
  71. - Handles modern type annotations (`str | Exception`)
  72. - Generates local configuration files
  73. ## Usage Examples
  74. ### Basic Search
  75. ```bash
  76. # Simple search with default engines
  77. searxng search "python tutorial"
  78. # Search with specific engines
  79. searxng search "machine learning" --engines duckduckgo,startpage
  80. # Search in specific category
  81. searxng search "neural networks" --category science
  82. ```
  83. ### Engine Management
  84. ```bash
  85. # List all available engines (compact overview)
  86. searxng engines
  87. # List common engines only (clean 4-column layout)
  88. searxng engines --common
  89. # List engines in specific category
  90. searxng engines --category general
  91. # List only common engines in a category
  92. searxng engines --category general --common
  93. # Search while disabling specific engines
  94. searxng search "web development" --disable google,bing
  95. ```
  96. ### Output Formats
  97. ```bash
  98. # Human-readable output (default)
  99. searxng search "AI research"
  100. # JSON output for scripting
  101. searxng search "data science" --format json
  102. # JSON output with specific engines
  103. searxng search "rust programming" --engines duckduckgo --format json > results.json
  104. ```
  105. ### Advanced Options
  106. ```bash
  107. # Search with language preference
  108. searxng search "tutorial python" --lang fr
  109. # Search with safe search enabled
  110. searxng search "programming" --safe 1
  111. # Search recent results only
  112. searxng search "tech news" --time week --category news
  113. # Search specific page
  114. searxng search "javascript" --page 2
  115. ```
  116. ### URL Content Retrieval
  117. ```bash
  118. # Fetch content from a single URL
  119. searxng fetch-urls "https://example.com"
  120. # Fetch content from multiple URLs in parallel
  121. searxng fetch-urls "https://site1.com" "https://site2.com" "https://site3.com"
  122. # Human-readable output (default)
  123. searxng fetch-urls "https://example.com"
  124. # JSON output for scripting
  125. searxng fetch-urls "https://docs.python.org" --format json > content.json
  126. # Control concurrency for rate limiting
  127. searxng fetch-urls url1 url2 url3 --concurrent 2
  128. ```
  129. ### Browse Available Options
  130. ```bash
  131. # List all search categories
  132. searxng categories
  133. # Get help for any command
  134. searxng search --help
  135. searxng engines --help
  136. ```
  137. ## Available Categories
  138. - **general** - General web search (51 engines)
  139. - **images** - Image search (34 engines)
  140. - **videos** - Video search (29 engines)
  141. - **news** - News search (18 engines)
  142. - **science** - Scientific publications (9 engines)
  143. - **it** - IT/Programming resources (44 engines)
  144. - **music** - Music search (10 engines)
  145. - **files** - File search (17 engines)
  146. - **maps** - Map search (3 engines)
  147. - And many more...
  148. ## Common Engines
  149. ⭐ **Most Popular:**
  150. - `duckduckgo` - Privacy-focused search
  151. - `startpage` - Google results without tracking
  152. - `brave` - Independent search index
  153. - `google` - Google search
  154. - `bing` - Microsoft search
  155. - `qwant` - European search engine
  156. ## Testing the CLI
  157. ### Test Basic Functionality
  158. ```bash
  159. # Test categories listing
  160. uv run searxng categories
  161. # Or: searxng categories
  162. # Test clean engine listing (shows popular engines in 4 columns)
  163. uv run searxng engines --common
  164. # Or: searxng engines --common
  165. # Test engine overview (compact category summary)
  166. uv run searxng engines
  167. # Or: searxng engines
  168. # Test simple search
  169. uv run searxng search "test query" --engines duckduckgo
  170. # Or: searxng search "test query" --engines duckduckgo
  171. ```
  172. ### Test Different Output Formats
  173. ```bash
  174. # Test human-readable output
  175. uv run searxng search "python" --engines duckduckgo | head -20
  176. # Or: searxng search "python" --engines duckduckgo | head -20
  177. # Test JSON output
  178. uv run searxng search "programming" --engines duckduckgo --format json | jq .
  179. # Or: searxng search "programming" --engines duckduckgo --format json | jq .
  180. ```
  181. ### Test Multiple Engines
  182. ```bash
  183. # Test with multiple engines
  184. uv run searxng search "web development" --engines duckduckgo,startpage
  185. # Or: searxng search "web development" --engines duckduckgo,startpage
  186. # Test engine filtering
  187. uv run searxng search "javascript" --category general --disable google,bing
  188. # Or: searxng search "javascript" --category general --disable google,bing
  189. ```
  190. ### Test Categories
  191. ```bash
  192. # Test different categories
  193. uv run searxng search "machine learning" --category science --engines arxiv
  194. # Or: searxng search "machine learning" --category science --engines arxiv
  195. uv run searxng search "react tutorial" --category it --engines github
  196. # Or: searxng search "react tutorial" --category it --engines github
  197. uv run searxng search "funny cats" --category images --engines duckduckgo_images
  198. # Or: searxng search "funny cats" --category images --engines duckduckgo_images
  199. ```
  200. ## Building Executable (Optional)
  201. To create a standalone executable:
  202. ```bash
  203. # Sync development dependencies (includes PyInstaller)
  204. uv sync
  205. # Build with PyInstaller (no code signing)
  206. uv run pyinstaller searxng.spec
  207. # Test the executable
  208. ./dist/searxng --help
  209. ./dist/searxng search "test" --engines duckduckgo
  210. ```
  211. ### Code Signing (macOS only)
  212. For distribution on macOS, you can optionally enable code signing if you have a valid Developer ID certificate:
  213. ```bash
  214. # Set environment variables for code signing
  215. export PYINSTALLER_CODESIGN_IDENTITY="Developer ID Application: Your Name"
  216. export PYINSTALLER_ENTITLEMENTS_FILE="entitlements.plist" # optional
  217. # Build with code signing
  218. uv run pyinstaller searxng.spec
  219. ```
  220. **Note:** The executable may have some engine loading issues. The Python version is recommended for full functionality.
  221. ## AI Assistant Integration
  222. SearXNG AI Kit includes an AI assistant feature that combines web search capabilities with powerful language models. The assistant can perform parallel searches and fetch content from multiple URLs to provide comprehensive research and answers.
  223. ### Ask Command (One-Shot Q&A)
  224. ```bash
  225. # Ask a question using the default model
  226. searxng ask "What are the latest developments in quantum computing?"
  227. # Use a model from the registry
  228. searxng ask "Research renewable energy trends" --model "opencode/big-pickle"
  229. # Use a LiteLLM model string directly
  230. searxng ask "Explain AI" --model "openai/gpt-4o-mini"
  231. # Get JSON output for programmatic use
  232. searxng ask "Compare Python vs JavaScript" --format json
  233. # Read prompt from stdin for longer questions
  234. echo "Analyze the current state of renewable energy adoption globally, including recent policy changes and technological breakthroughs" | searxng ask
  235. # Interactive stdin mode
  236. searxng ask
  237. # (then type your question and press Ctrl+D)
  238. # Pipe from file
  239. searxng ask < my_research_question.txt
  240. ```
  241. ### Chat Command (Interactive Conversations)
  242. ```bash
  243. # Start an interactive chat session (uses default model)
  244. searxng chat
  245. # Use a model from the registry
  246. searxng chat --model "opencode/glm-4.7"
  247. # Use a LiteLLM model string directly
  248. searxng chat --model "openai/gpt-4o-mini"
  249. # Use OpenRouter models
  250. searxng chat --model "openrouter/anthropic/claude-3.5-sonnet"
  251. # Use custom API endpoint
  252. searxng chat --base-url "https://api.openai.com/v1"
  253. ```
  254. The chat command maintains conversation history and allows follow-up questions:
  255. ```
  256. You: What's the weather like in Tokyo?
  257. Assistant: [searches for current Tokyo weather information]
  258. You: How about tomorrow?
  259. Assistant: [remembers we're discussing Tokyo weather and searches for tomorrow's forecast]
  260. You: What should I wear?
  261. Assistant: [provides clothing recommendations based on the weather information from previous searches]
  262. ```
  263. **Chat Features:**
  264. - **Conversation Memory**: Remembers all previous messages in the session
  265. - **Context Awareness**: References earlier parts of the conversation
  266. - **Chat History**: Automatically saves conversations to markdown files
  267. - **Model Display**: Shows model name (e.g., `o3`) instead of generic "Assistant"
  268. - **Progress Indicator**: Animated spinner while waiting for AI responses
  269. - **Exit Commands**: Type `exit`, `quit`, `bye`, or press Ctrl+C to end
  270. - **Web Search**: Full access to search tools during conversations
  271. - **Tool Visibility**: Shows search queries and URL fetches in real-time
  272. **Chat History Location:**
  273. - Saved to: `~/.local/share/searxng-ai-kit/chats/` (XDG Base Directory spec)
  274. - Format: `chat-YYYY-MM-DD_HH-MM-SS-modelname.md`
  275. - Example: `chat-2025-06-29_14-30-15-o3.md`
  276. ### Model Registry
  277. SearXNG AI Kit uses a model registry to manage AI model configurations. Models from various providers can be imported and used with simple names.
  278. #### List Available Models
  279. ```bash
  280. # List all models in registry
  281. searxng models list
  282. # Show details for a specific model
  283. searxng models show "opencode/big-pickle"
  284. ```
  285. #### Set Default Model
  286. ```bash
  287. # Set a default model (used when --model not specified)
  288. searxng models set-default "opencode/big-pickle"
  289. # Show current default
  290. searxng models set-default
  291. ```
  292. #### Import from OpenCode
  293. If you use [OpenCode](https://opencode.ai), you can import your configured models:
  294. ```bash
  295. # Preview what would be imported
  296. searxng models import opencode --dry-run
  297. # Import models from OpenCode config
  298. searxng models import opencode
  299. ```
  300. This imports models from `~/.config/opencode/opencode.jsonc` and `~/.local/share/opencode/auth.json`.
  301. #### Using Models
  302. ```bash
  303. # Use a model from the registry
  304. searxng ask "What is quantum computing?" --model "opencode/big-pickle"
  305. # Use with chat
  306. searxng chat --model "opencode/glm-4.7"
  307. # If default is set, just run without --model
  308. searxng ask "Explain machine learning"
  309. ```
  310. The `--model` flag accepts:
  311. - **Registry names**: `opencode/big-pickle`, `cli-proxy-api/claude-sonnet-4`
  312. - **LiteLLM strings**: `openai/gpt-4o`, `anthropic/claude-3-5-sonnet`
  313. #### Manual Model Management
  314. ```bash
  315. # Add a model manually
  316. searxng models add "my-model" --type openai --model-id gpt-4o --api-key "sk-..."
  317. # Remove a model
  318. searxng models remove "my-model"
  319. # Edit models file directly
  320. searxng models edit
  321. ```
  322. Models are stored in `~/.config/searxng/models.toml`.
  323. ### API Key Configuration
  324. Set one of these environment variables (used when model doesn't have stored API key):
  325. ```bash
  326. # OpenAI (recommended)
  327. export OPENAI_API_KEY="your-openai-key"
  328. # OpenRouter (access to many models)
  329. export OPENROUTER_API_KEY="your-openrouter-key"
  330. # Anthropic
  331. export ANTHROPIC_API_KEY="your-anthropic-key"
  332. # Google
  333. export GOOGLE_API_KEY="your-google-key"
  334. ```
  335. ### OpenRouter Integration
  336. OpenRouter provides access to many AI models through a single API. SearXNG Kit has native OpenRouter support:
  337. ```bash
  338. # Set OpenRouter API key
  339. export OPENROUTER_API_KEY="your-openrouter-key"
  340. # Use OpenRouter models with native prefix
  341. searxng ask "Analyze market trends" --model "openrouter/openai/gpt-4o-mini"
  342. searxng ask "Technical research" --model "openrouter/anthropic/claude-3.5-sonnet"
  343. # Use custom base URL (alternative method)
  344. searxng ask "Question" --base-url "https://openrouter.ai/api/v1" --model "openai/gpt-4o-mini"
  345. ```
  346. ### CLI Proxy API Integration
  347. SearXNG AI Kit integrates with [CLI Proxy API](https://github.com/router-for-me/CLIProxyAPI) to provide access to multiple AI providers through their OAuth and subscription plans - **no API keys needed!** Use your existing Claude Pro, ChatGPT Plus, or Gemini Advanced subscriptions.
  348. #### Step 1: Install CLI Proxy API
  349. Download the latest release from GitHub:
  350. ```bash
  351. # macOS (Apple Silicon)
  352. curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-darwin-arm64 -o cli-proxy-api
  353. chmod +x cli-proxy-api
  354. sudo mv cli-proxy-api /usr/local/bin/
  355. # macOS (Intel)
  356. curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-darwin-amd64 -o cli-proxy-api
  357. chmod +x cli-proxy-api
  358. sudo mv cli-proxy-api /usr/local/bin/
  359. # Linux (x64)
  360. curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cli-proxy-api-linux-amd64 -o cli-proxy-api
  361. chmod +x cli-proxy-api
  362. sudo mv cli-proxy-api /usr/local/bin/
  363. ```
  364. Or build from source: https://github.com/router-for-me/CLIProxyAPI
  365. #### Step 2: Create Configuration File
  366. Create `~/.cli-proxy-api/config.yaml`:
  367. ```yaml
  368. host: "127.0.0.1"
  369. port: 8317
  370. auth-dir: "~/.cli-proxy-api"
  371. ```
  372. #### Step 3: Authenticate with AI Providers
  373. Log in to the providers you want to use:
  374. ```bash
  375. # Claude (Anthropic) - opens browser for OAuth
  376. cli-proxy-api -claude-login
  377. # Google Gemini - opens browser for OAuth
  378. cli-proxy-api -login
  379. # OpenAI Codex - opens browser for OAuth
  380. cli-proxy-api -codex-login
  381. # Qwen - opens browser for OAuth
  382. cli-proxy-api -qwen-login
  383. ```
  384. Each login opens your browser for OAuth authentication. After authenticating, tokens are stored in `~/.cli-proxy-api/`.
  385. #### Step 4: Configure SearXNG
  386. Tell SearXNG where your CLI Proxy API config is:
  387. ```bash
  388. # Point to your config file
  389. searxng cli-proxy-api set-config ~/.cli-proxy-api/config.yaml
  390. # Enable the integration
  391. searxng cli-proxy-api enable
  392. # Verify everything is working
  393. searxng cli-proxy-api status
  394. ```
  395. #### Step 5: Set a Default Model (Optional)
  396. ```bash
  397. # Set a default model so you don't need --model every time
  398. searxng cli-proxy-api set-default-model claude-sonnet-4-5-20250929
  399. # Now just use ask/chat without --model
  400. searxng ask "Explain quantum computing"
  401. searxng chat
  402. ```
  403. #### Step 6: Use It!
  404. ```bash
  405. # List all available models
  406. searxng models
  407. # Use CLI Proxy API models (with explicit model)
  408. searxng ask --model cli-proxy-api/claude-sonnet-4-5-20250929 "Explain quantum computing"
  409. # Or just use the default (if set)
  410. searxng ask "What's new in AI?"
  411. # Start interactive chat
  412. searxng chat
  413. ```
  414. #### Available Commands
  415. ```bash
  416. # List all available models (shows default)
  417. searxng models
  418. # Check status
  419. searxng cli-proxy-api status
  420. # Set/clear default model
  421. searxng cli-proxy-api set-default-model claude-sonnet-4-5-20250929
  422. searxng cli-proxy-api clear-default-model
  423. # Enable/disable integration
  424. searxng cli-proxy-api enable
  425. searxng cli-proxy-api disable
  426. # Set config path (if not in default location)
  427. searxng cli-proxy-api set-config /path/to/config.yaml
  428. # Clear explicit config (use auto-detection)
  429. searxng cli-proxy-api clear-config
  430. ```
  431. #### How It Works
  432. When you use a `cli-proxy-api/*` model:
  433. 1. SearXNG automatically starts a managed cli-proxy-api subprocess on a random port
  434. 2. Your OAuth tokens (stored by cli-proxy-api) handle authentication
  435. 3. Requests route through the local proxy to AI providers
  436. 4. The proxy handles token refresh and provider-specific quirks
  437. **Supported Providers:**
  438. - **Anthropic Claude** (via OAuth) - claude-sonnet-4-5, claude-opus-4, etc.
  439. - **Google Gemini** (via OAuth) - gemini-2.5-pro, gemini-2.5-flash, etc.
  440. - **OpenAI** (via OAuth) - gpt-4o, gpt-4o-mini, etc.
  441. - **Alibaba Qwen** (via OAuth)
  442. - Any OpenAI-compatible provider (via config)
  443. ### Custom API Endpoints
  444. Use custom OpenAI-compatible endpoints:
  445. ```bash
  446. # Via environment variable
  447. export OPENAI_BASE_URL="https://api.openai.com/v1"
  448. searxng ask "Question"
  449. # Via command line flag (overrides environment)
  450. searxng ask "Question" --base-url "https://custom-endpoint.com/v1"
  451. ```
  452. ### Available AI Tools
  453. The assistant has access to these tools for research:
  454. - **web_search**: Search using SearXNG's 180+ engines
  455. - **multi_web_search**: Run multiple searches in parallel
  456. - **fetch_url**: Extract content from a single URL
  457. - **fetch_urls**: Fetch content from multiple URLs simultaneously
  458. ## MCP Server Integration
  459. SearXNG AI Kit includes a Model Context Protocol (MCP) server for AI application integration. This allows AI assistants like Claude to search the web and fetch URL content directly.
  460. ### Starting the MCP Server
  461. ```bash
  462. # Start the MCP server (runs until Ctrl+C)
  463. searxng mcp-server
  464. ```
  465. ### Available MCP Tools
  466. 1. **web_search**: Search using SearXNG's 180+ search engines
  467. - Supports all search parameters (query, category, engines, language, etc.)
  468. - Returns structured JSON results
  469. 2. **multi_web_search**: Run multiple search queries in parallel
  470. - Execute multiple searches simultaneously for comprehensive coverage
  471. - Faster than sequential searches for research tasks
  472. 3. **fetch_url**: Retrieve and extract content from a single URL using Jina.ai
  473. - Clean text extraction and content processing
  474. 4. **fetch_urls**: Retrieve and extract content from multiple URLs in parallel
  475. - Maintains order of results when using arrays
  476. - Handles errors gracefully while preserving partial results
  477. 5. **ask**: Ask an AI assistant with access to all the above tools
  478. - Uses OpenAI o3 model by default
  479. - Can recursively use search and URL fetching tools
  480. - Supports custom models and base URLs via parameters
  481. ### Claude Desktop Configuration
  482. Add this to your `claude_desktop_config.json`:
  483. ```json
  484. {
  485. "mcpServers": {
  486. "searxng": {
  487. "command": "searxng",
  488. "args": ["mcp-server"]
  489. }
  490. }
  491. }
  492. ```
  493. ### Environment Variables
  494. - `JINA_API_KEY`: Optional API key for enhanced Jina.ai URL reading features
  495. ## Troubleshooting
  496. ### Common Issues
  497. 1. **No results returned:**
  498. - Try different engines: `--engines duckduckgo,startpage`
  499. - Check if engines are available: `searxng engines --common`
  500. 2. **Engine errors in output:**
  501. - Normal behavior - some engines may fail to initialize
  502. - Errors are printed to stderr, results to stdout
  503. 3. **Slow searches:**
  504. - Normal for first run (engine initialization)
  505. - Use fewer engines: `--engines duckduckgo` instead of defaults
  506. ### CLI Proxy API Issues
  507. **"cli-proxy-api not found"**
  508. - Install cli-proxy-api: https://github.com/router-for-me/CLIProxyAPI
  509. - Ensure it's in your PATH
  510. **"No cli-proxy-api config found"**
  511. - Create config at `~/.cli-proxy-api/config.yaml`
  512. - Or set path: `searxng cli-proxy-api set-config /path/to/config.yaml`
  513. **"Failed to start cli-proxy-api"**
  514. - Check config syntax: `cli-proxy-api -config ~/.cli-proxy-api/config.yaml`
  515. - Check for port conflicts
  516. **"No models available"**
  517. - Run OAuth login: `cli-proxy-api -login`
  518. - Check that config has valid credentials
  519. - Try `searxng cli-proxy-api status` to see detailed status
  520. ### Performance Tips
  521. - Use `--engines` to specify fast, reliable engines
  522. - Redirect stderr to hide engine errors: `2>/dev/null`
  523. - Use JSON format for programmatic usage
  524. ## Example Scripts
  525. ### Search and save results
  526. ```bash
  527. #!/bin/bash
  528. query="$1"
  529. searxng search "$query" --format json --engines duckduckgo,startpage > "results_$(date +%Y%m%d_%H%M%S).json"
  530. ```
  531. ### Quick search function for .bashrc
  532. ```bash
  533. search() {
  534. searxng search "$*" --engines duckduckgo 2>/dev/null
  535. }
  536. ```
  537. ## Python Library Usage
  538. SearXNG AI Kit can also be used as a Python library in your projects:
  539. ```python
  540. import searxng
  541. # Basic search
  542. results = searxng.search("python tutorial", max_results=10)
  543. print(f"Found {results['total_results']} results")
  544. # Fetch URL content
  545. content = searxng.fetch_url("https://example.com")
  546. if content["success"]:
  547. print(f"Title: {content['title']}")
  548. # Ask AI assistant with web search access
  549. response = searxng.ask("What are the latest developments in quantum computing?")
  550. if response["success"]:
  551. print(response["response"])
  552. # Ask with custom model
  553. response = searxng.ask(
  554. "Research renewable energy trends",
  555. model="openrouter/openai/gpt-4o-mini"
  556. )
  557. # Parallel URL fetching
  558. urls = ["https://site1.com", "https://site2.com"]
  559. contents = searxng.fetch_urls(urls, max_concurrent=3)
  560. # Using client with defaults
  561. client = searxng.SearXNGClient(
  562. default_engines=["duckduckgo", "startpage"],
  563. default_max_results=15
  564. )
  565. results = client.search("machine learning")
  566. ai_response = client.ask("Explain machine learning basics")
  567. ```
  568. ### Library API
  569. - `searxng.search(query, **kwargs)` - Web search with customizable parameters
  570. - `searxng.fetch_url(url)` - Extract content from single URL
  571. - `searxng.fetch_urls(urls, max_concurrent=5)` - Parallel URL content extraction
  572. - `searxng.ask(prompt, model="openai/o3", base_url=None)` - AI assistant with web search tools
  573. - `searxng.get_available_engines()` - Get engine information
  574. - `searxng.get_categories()` - Get search categories
  575. - `searxng.SearXNGClient(**defaults)` - Client class with reusable settings
  576. All functions have async variants (`search_async`, `fetch_url_async`, `ask_async`, etc.).
  577. ## License
  578. This CLI tool uses SearXNG, which is licensed under AGPL-3.0. See the main repository for full license details.

Ratings and comments

Sign in to rate this skill.

Sign in

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