Server facts
SearXNG MCP Server
Project
- Author
- ihor-sokoliuk
- Repository
- github.com/ihor-sokoliuk/mcp-searxng
- License
- MIT
- Category
- Search & Web Data
Tech
- Runtime / language
- node
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 1,312
- Last commit
- Data as of
Tags
- Content Extraction
- Search Suggestions
- Searxng
- Self Hosted
- Web Search
Overview
SearXNG MCP Server is a standalone Node.js process that connects an assistant to one or more existing SearXNG instances. It is not installed inside SearXNG as a plugin. Search requests can select a page, time range, language, safety level, categories, and engines. Results are available as formatted text or SearXNG-shaped JSON, with relevance and result-count controls. Text output also surfaces direct answers, corrections, suggestions, and infobox information when supplied by the search backend. Additional tools provide autocomplete suggestions and discover the categories, engines, locales, defaults, and plugins exposed by reachable instances.
Beyond search, the server reads URL content with heading, section, paragraph, and character-range controls. HTML becomes Markdown, while JSON and supported text types receive readable representations. Binary downloads, including PDFs and archives, are rejected rather than returned as raw bytes. URL content is cached with an expiry time. Operators configure the backend through SEARXNG_URL, which can hold interchangeable replicas for failover or optional parallel fanout. The preferred backend setup enables SearXNG's JSON format. An opt-in HTML fallback helps with some public instances but supplies less metadata and uses best-effort parsing. Launch choices include npx, a global package, Docker, and HTTP mode. Standard input/output remains the default for local MCP clients.
Install & configure
Requirements
- Node.js and npx
- An accessible SearXNG instance, preferably with JSON search enabled
- An MCP-compatible client
npx -y mcp-searxngThe README's quick start uses npx. Docker and global-package alternatives are documented. MCP_HTTP_PORT enables HTTP mode. SEARXNG_HTML_FALLBACK is an optional compatibility measure when JSON responses are unavailable.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"
}
}
}
}Config file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"
}
}
}
}Config file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
{
"servers": {
"mcp-searxng": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"
}
}
}
}Config file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-searxng": {
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"
}
}
}
}Config file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
{
"mcpServers": {
"mcp-searxng": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-searxng"
],
"env": {
"SEARXNG_URL": "<SearXNG instance URL or semicolon-separated interchangeable replica URLs>"
}
}
}
}Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| searxng_web_search | Search SearXNG with pagination, filters, and text or JSON responses. |
| searxng_search_suggestions | Request autocomplete suggestions for a partial or complete query. |
| searxng_instance_info | Inspect shared and available capabilities across configured reachable instances. |
| web_url_read | Read supported URL content with section, paragraph, heading, and character-range controls. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Add filtered web research to an assistant using an existing SearXNG deployment.
- Read selected sections or headings from a result URL.
- Discover available search engines before selecting query filters.
- Use interchangeable SearXNG replicas for failover.
Strengths
- Uses a configurable SearXNG backend instead of a required search API key.
- Combines search, suggestions, instance discovery, and URL reading.
- Supports replica failover and optional parallel fanout.
Limitations
- Requires an accessible SearXNG instance.
- HTML fallback is best-effort and loses relevance scores and engine metadata.
- The URL reader rejects PDFs and other binary downloads.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
