searxng-search-mcp
Provides tools for interacting with a SearXNG instance, enabling web search with ranked results, instant answers, query suggestions, and configurable search parameters such as categories, language, time range, engines, safesearch, and result limits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@searxng-search-mcp search the web for news about the EU AI Act from the past week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
searxng-search-mcp
An MCP server that exposes SearXNG web search and search suggestions to AI clients, distributed via npx.
Tools
Tool | Description |
| Full web search: ranked results, instant answers, and query suggestions. |
| Autocomplete suggestions for a partial query. |
searxng_web_search parameters
Parameter | Type | Description |
| string | Required. Search query. |
| string | Comma-separated categories, e.g. |
| string | Result language as BCP-47 code, e.g. |
| string | One of |
| integer | Page number, 1-based (default 1). |
| string | Comma-separated SearXNG engine names to use instead of categories. |
| integer |
|
| integer | Maximum number of results to return, clamped to 1-50 (default from |
searxng_suggest parameters
Parameter | Type | Description |
| string | Required. Partial query to complete. |
Related MCP server: SearXNG MCP Server
Requirements
Node.js >= 20
A SearXNG instance with the JSON format enabled. Most public instances block the JSON API (403), so a self-hosted instance is the supported path — see Running a local SearXNG instance.
Configuration
Environment variable | Required | Default | Description |
| yes | — | Base URL of your SearXNG instance, e.g. |
| no |
| Request timeout in milliseconds. |
| no |
| Default maximum number of results, clamped to 1-50. |
Usage
All clients use the same command: npx -y searxng-search-mcp, configured with the SEARXNG_URL environment variable.
Claude Desktop
claude_desktop_config.json:
{
"mcpServers": {
"searxng-search-mcp": {
"command": "npx",
"args": ["-y", "searxng-search-mcp"],
"env": {
"SEARXNG_URL": "http://localhost:8888"
}
}
}
}Claude Code
claude mcp add searxng-search-mcp --env SEARXNG_URL=http://localhost:8888 -- npx -y searxng-search-mcpopencode
opencode.json:
{
"mcp": {
"searxng-search-mcp": {
"type": "local",
"command": ["npx", "-y", "searxng-search-mcp"],
"enabled": true,
"environment": {
"SEARXNG_URL": "http://localhost:8888"
}
}
}
}Cursor
.cursor/mcp.json:
{
"mcpServers": {
"searxng-search-mcp": {
"command": "npx",
"args": ["-y", "searxng-search-mcp"],
"env": {
"SEARXNG_URL": "http://localhost:8888"
}
}
}
}VS Code
.vscode/mcp.json:
{
"servers": {
"searxng-search-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "searxng-search-mcp"],
"env": {
"SEARXNG_URL": "http://localhost:8888"
}
}
}
}Running a local SearXNG instance
SearXNG disables the JSON output format by default. The instance must be configured to allow it, otherwise search requests return 403. This repository ships a ready-to-use Docker Compose setup.
docker-compose.yml:
services:
searxng:
image: docker.io/searxng/searxng:latest
ports:
- "8888:8080"
volumes:
- ./searxng:/etc/searxng
restart: unless-stoppedsearxng/settings.yml:
use_default_settings: true
server:
secret_key: "searxng-search-mcp-dev-instance-change-me"
search:
formats:
- html
- jsonStart and verify:
docker compose up -d
curl 'http://localhost:8888/search?q=test&format=json'The curl command must return a JSON object with a results array. If it returns 403, json is missing from search.formats in settings.yml — the two files above are the exact fix.
Troubleshooting
403 Forbidden — the JSON format is not enabled on the instance. Add
jsontosearch.formatsin the SearXNGsettings.ymland restart (see above).429 Too Many Requests — the instance rate limiter is throttling requests. Self-host an instance, or add your IP to the limiter
pass_iplist insettings.yml.Timeout / network error — check that
SEARXNG_URLpoints at a reachable instance and adjustSEARXNG_TIMEOUT_MSif the instance is slow.
Development
npm install # installs and builds (prepare script)
npm test # unit + tool + e2e tests (uses a mock SearXNG server)
npm run test:e2e # e2e only: builds, then spawns dist/index.js against a mock
docker compose up -d
SEARXNG_INTEGRATION_URL=http://localhost:8888 npm run test:integrationSmoke-test the server with the MCP Inspector. This lists the server's tools (Inspector v2 sanitizes inherited env, so SEARXNG_URL must be passed via -e):
npx -y @modelcontextprotocol/inspector --cli node dist/index.js -e SEARXNG_URL=http://localhost:8888 --method tools/list --format jsonOmit --method to open the interactive web UI instead.
Publishing
Releases are published to npm by .github/workflows/publish.yml when a v* tag is pushed. It uses npm trusted publishing (tokenless OIDC) with provenance.
One-time maintainer setup:
Enable 2FA on your npm account.
Configure a trusted publisher on npmjs.com bound to this repository and the
publish.ymlworkflow.Make the repository public before the first release — npm provenance requires a public GitHub repository.
The workflow runs on Node 24, which ships npm >= 11.5 (required for tokenless trusted publishing).
License
Available Tools
2 toolssearxng_suggestCRead-only
Get search query autocomplete suggestions from the SearXNG instance.
Inputs: query (required). Returns: suggestions
searxng_web_searchBRead-only
Search the web through a SearXNG instance. Returns ranked results, instant answers, and query suggestions.
Inputs: query (required), pageno, engines, language, +4 more. Returns: query, answers, results, suggestions, +1 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one performs web searches, the other provides autocomplete suggestions. There is no overlap or ambiguity.
Both names follow a consistent pattern: searxng_<action> (searxng_web_search and searxng_suggest). The naming is predictable and readable.
With only 2 tools, the surface is thin for a search server. While each tool earns its place, the lack of additional features like pagination or site-specific search makes it borderline.
The tools cover basic search and suggestions but miss common operations like advanced search parameters, result filtering, or pagination. This is a notable gap for a search-oriented server.
Related MCP Connectors
Web search, Google SERP, page extraction to markdown and cited answers for AI agents.
Unofficial Serper MCP — wraps the Serper Google Search API (serper.dev)
Provides AI assistants with access to Seltz's powerful Web Search capabilities.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform privacy-respecting web searches through SearXNG, with support for multiple search engines, categories, and advanced filtering options.27ISC
- AlicenseAqualityDmaintenanceEnables web search capabilities via a SearXNG instance, allowing for filtered searches across categories like news, images, and science. It supports multi-language queries, time-range filtering, and safe search options to provide formatted results with metadata.1180 npmMIT
- AlicenseAqualityBmaintenanceEnables privacy-friendly web searches through the SearXNG engine, with support for multiple engines, categories, languages, time ranges, and configurable result counts.1408 PyPI1AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to run privacy-friendly web, news, image, and video searches through their own SearXNG instance, with autocomplete, instance/engine discovery, and pagination, language, time-range, SafeSearch, engine, and domain filters. It also fetches pages and returns clean readable text, stripping headers, footers, navigation, sidebars, ads, and comment sections by default while letting the agent re-include them per call.95 npmMIT