| name | searxng-search |
| description | Search the web using a local SearXNG metasearch engine via MCP. Use this skill when the user asks to search the web, look something up online, find information on the internet, research a topic, check recent news, or when you need up-to-date information that is not in your training data. USE FOR: web search, internet lookup, finding recent information, researching topics, checking news, discovering URLs, finding documentation online, verifying facts against current sources. DO NOT USE FOR: searching the local codebase (use Grep/Glob instead), reading known URLs (use WebFetch instead), or querying internal databases. |
| compatibility | Requires Docker Desktop or Podman (with compose support) and Node.js 18+. |
| metadata | {"version":"1.0"} |
| allowed-tools | Bash(node:*) Bash(docker:*) Bash(podman:*) |
SearXNG Web Search
Search the web privately using a local SearXNG metasearch engine. SearXNG
aggregates results from multiple search engines (Google, Bing, DuckDuckGo,
Brave, and more) without tracking or profiling. The skill runs two containers —
SearXNG and an MCP server — that expose search tools directly to the agent.
Prerequisites
- Docker Desktop or Podman (4.7+ recommended for built-in compose)
- Node.js 18+ (already required by the
alle-skills CLI)
- Run
install.js first — it detects your container runtime, generates config,
pulls images, and registers the MCP server in your agent config
node <SKILL_DIR>/install.js
After installation, restart your agent to pick up the new MCP server.
Configuration
Configuration lives in config.env in the skill directory.
| Key | Default | Description |
|---|
SEARXNG_MCP_PORT | 32123 | Port for the MCP server on localhost |
COMPOSE_CMD | (auto-detect) | Override compose command (e.g. docker compose or podman compose) |
Override via environment variables or by editing config.env.
SearXNG engine settings are in searxng/settings.yml (generated by install.js
with a random secret key — not committed to git).
Architecture
Container Network (compose)
├── searxng docker.io/searxng/searxng:latest port 8080 (internal)
└── searxng-mcp ghcr.io/aicrafted/searxng-mcp:latest port 32123 → host
The agent connects to the MCP server at http://localhost:32123/ as a remote
MCP endpoint. SearXNG is internal-only — not exposed to the host.
CLI Reference
All lifecycle commands use the Node.js script. Set SKILL_DIR to the skill
installation path:
SKILL_DIR=~/.claude/skills/searxng-search
Start containers
node "$SKILL_DIR/scripts/searxng_ctl.js" start
Auto-detects Docker or Podman. If using Podman and the machine is not running,
it starts the machine first. Returns JSON:
{"ok": true, "runtime": "docker", "message": "Containers started.", "mcp_port": 32123}
Stop containers
node "$SKILL_DIR/scripts/searxng_ctl.js" stop
Check status
node "$SKILL_DIR/scripts/searxng_ctl.js" status
Returns JSON with container states:
{"ok": true, "running": true, "container_count": 2, "containers": [...], "mcp_port": 32123}
Health check
node "$SKILL_DIR/scripts/searxng_ctl.js" health
Verifies the MCP endpoint is responding on localhost:
{"ok": true, "healthy": true, "status_code": 200, "url": "http://127.0.0.1:32123/"}
Workflow
Follow these steps when a web search is needed:
-
Try the MCP tool directly. Call searxng_search (the MCP tool). If it
responds, skip to step 4.
-
If the MCP tool fails (connection error): The containers are likely down.
Start them:
node "$SKILL_DIR/scripts/searxng_ctl.js" start
Wait ~5 seconds for SearXNG to initialize.
-
Verify the service is healthy:
node "$SKILL_DIR/scripts/searxng_ctl.js" health
-
Search using MCP tools. These are called directly as MCP tools — not
via Bash:
-
Present results to the user with source URLs.
Note: The MCP tool names may be prefixed by the agent with the server name
(e.g. searxng_searxng_search). This depends on the agent implementation.
Common Questions
| User asks | Agent does |
|---|
| "search for X" / "look up X" / "find X online" | Call searxng_search with query: "X" |
| "what's the latest news about X?" | searxng_search with query: "X", categories: "news", time_range: "day" |
| "find Python docs for X" | searxng_search with query: "X", categories: "it" |
| "search for X in the last month" | searxng_search with query: "X", time_range: "month" |
| "what search engines are available?" | Call searxng_get_info |
| "is the search service running?" | Run node "$SKILL_DIR/scripts/searxng_ctl.js" status |
| "start the search service" | Run node "$SKILL_DIR/scripts/searxng_ctl.js" start |
| "stop the search service" | Run node "$SKILL_DIR/scripts/searxng_ctl.js" stop |
Error Handling
| Error | Cause | Fix |
|---|
| MCP tool connection refused | Containers not running | Run searxng_ctl.js start |
No container runtime found | Docker/Podman not installed | Install Docker Desktop or Podman |
No Podman machine found | Podman machine not initialized | Run podman machine init && podman machine start |
Podman machine exists but is not running | Machine stopped | Run podman machine start |
| Port 32123 already in use | Another process on that port | Change SEARXNG_MCP_PORT in config.env and restart |
SearXNG settings not found | install.js was not run | Run node <SKILL_DIR>/install.js |
| MCP server exits immediately | SearXNG not ready yet | Wait a few seconds, then run searxng_ctl.js start again |
| Empty search results | JSON format not enabled in SearXNG | Verify searxng/settings.yml includes json in search.formats |
Tips
- Use
categories: "news" with time_range: "day" for recent news
- Use
categories: "it" for programming and tech-specific results
- Use
response_format: "json" when you need structured data with relevance
scores and engine attribution
- The SearXNG instance is private and local — no data is stored, no tracking
- Containers have
restart: unless-stopped — they survive host reboots (if
Docker Desktop / Podman machine is set to auto-start)
- Check logs for debugging: run
docker logs searxng or podman logs searxng
