Registry / http-networking / mcp-searxng

mcp-searxng

JSON →
library0.1.0jsnpmunverified

mcp-searxng is a Node.js server that acts as an integration layer between AI assistants adhering to the Model Context Protocol (MCP) and a SearXNG instance. It enables AI models to perform web searches and read URL content by abstracting the SearXNG API. The current stable version is 1.0.3, with frequent minor releases focusing on bug fixes, performance enhancements, and new features. Key differentiators include robust web search with pagination, advanced URL content extraction (including sections, paragraph ranges, and headings), intelligent caching, and comprehensive time/language/safe search filtering. It's crucial to note that this is a standalone server and not a plugin for SearXNG itself; it connects to any existing SearXNG instance via its HTTP JSON API.

npm install mcp-searxng
INSTALL
IMPORT
SIG · MCP-SEARXNG
M
mcp-searxng
http-networkingjavascriptv0.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

McpServer
import { McpServer } from 'mcp-searxng';
const McpServer = require('mcp-searxng').McpServer;
The primary interaction is running `mcp-searxng` as a CLI, but programmatic integration is possible for advanced use cases, typically for ESM projects.
SearxngWebSearchTool
import { SearxngWebSearchTool } from 'mcp-searxng';
This represents one of the core tools exposed by the MCP server. It is likely exported directly from the main package entry.
McpSearxngServerOptions
import { McpSearxngServerOptions } from 'mcp-searxng';
Configuration interface for programmatic server instantiation, useful for TypeScript projects to ensure correct options.

This code demonstrates how to programmatically start the MCP SearXNG server, an alternative to running it via the `npx` command. It initializes the server using environment variables and handles graceful shutdown signals.

import { McpServer } from 'mcp-searxng'; interface EnvConfig { SEARXNG_URL: string; MCP_LOG_LEVEL?: string; // Add other relevant environment variables here as needed } async function startMcpSearxngServer() { const config: EnvConfig = { SEARXNG_URL: process.env.SEARXNG_URL ?? '', MCP_LOG_LEVEL: process.env.MCP_LOG_LEVEL }; if (!config.SEARXNG_URL) { console.error('Error: SEARXNG_URL environment variable is required.'); process.exit(1); } console.log(`Attempting to start MCP SearXNG server for URL: ${config.SEARXNG_URL}`); try { // Assuming McpServer constructor takes an options object derived from env // and automatically registers internal tools like SearxngWebSearchTool. const server = new McpServer({ searxngUrl: config.SEARXNG_URL, logLevel: config.MCP_LOG_LEVEL || 'info' // Add other options like proxy settings if exposed programmatically }); await server.start(); console.log('MCP SearXNG server successfully started. Listening for MCP messages on STDIO.'); process.on('SIGINT', async () => { console.log('SIGINT received. Shutting down server...'); await server.stop(); // Assuming a stop method exists process.exit(0); }); process.on('SIGTERM', async () => { console.log('SIGTERM received. Shutting down server...'); await server.stop(); process.exit(0); }); } catch (error) { console.error('Failed to start MCP SearXNG server:', error instanceof Error ? error.message : String(error)); process.exit(1); } } startMcpSearxngServer();
Debug
Known issues
gotchaThe `mcp-searxng` package is a standalone server for the Model Context Protocol, not a plugin that can be directly installed into a SearXNG instance. It connects to an existing, separately deployed SearXNG instance.
fix
Ensure you have a running SearXNG instance available at the URL specified by `SEARXNG_URL`. Do not attempt to install `mcp-searxng` within your SearXNG setup.
affects: >=0.1.0
breakingVersion 1.0.3 fixed a critical issue where the server would crash with an 'Already connected' error when attempting to create a new `McpServer` per HTTP session. While a fix, this indicates previous instability in session management.
fix
Upgrade to version 1.0.3 or higher to prevent crashes related to server instance re-initialization. Ensure your deployment strategy correctly manages server lifecycles.
affects: >=0.1.0 <1.0.3
gotchaImproper `SEARXNG_URL` configuration can lead to operational failures. Version 1.0.1 enhanced validation and error handling for this critical environment variable.
fix
Always set the `SEARXNG_URL` environment variable to a valid and accessible SearXNG instance URL. Verify the URL is correctly formatted and that the SearXNG instance is running and reachable from the `mcp-searxng` server.
affects: >=0.1.0
gotchaSearXNG instances may return HTTP 403 Forbidden errors, particularly when the JSON output format is requested. Troubleshooting documentation was added in v0.10.0 for this common issue.
fix
Consult the `mcp-searxng` documentation or SearXNG's documentation regarding JSON format 403 errors. This often involves checking SearXNG configuration (e.g., `settings.json`) for allowed request types, user agents, or IP restrictions.
affects: >=0.1.0
gotchaProxy configuration can be complex, with features like separate proxy configurations and custom User-Agent headers added in v0.10.0, and `NO_PROXY` support in v0.7.9. Incorrect settings can prevent `mcp-searxng` from reaching SearXNG or external URLs for content reading.
fix
Carefully review the proxy documentation for `mcp-searxng` and ensure all relevant environment variables (e.g., `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`) are correctly configured to match your network environment. Test connectivity thoroughly.
affects: >=0.7.8
gotchaLogging compliance with MCP STDIO was improved in v0.9.1 by changing `console.log` to `console.error` for error messages. This can affect how external MCP clients parse and display server output.
fix
Ensure any custom parsing logic for `mcp-searxng`'s STDIO output accounts for this change if you are running older versions or have strict log processing requirements. Upgrade to v0.9.1+ for better MCP compliance.
affects: >=0.1.0 <0.9.1
Errors
Common errors & fixes
Error: read ECONNRESET
Network connection dropped or reset during communication with the SearXNG instance, possibly due to a proxy issue, firewall, or an unresponsive SearXNG server.
fix
Check network connectivity between `mcp-searxng` and your SearXNG instance. Verify proxy settings, firewall rules, and ensure the SearXNG server is stable and responsive. Examine SearXNG logs for connection-related errors.
Error: SEARXNG_URL environment variable is required.
The essential environment variable for specifying the SearXNG instance URL is missing or empty.
fix
Set the `SEARXNG_URL` environment variable to the full URL of your SearXNG instance (e.g., `https://my-searxng.example.com`). This is typically done in the `env` section of your MCP client configuration or command-line environment.
Failed to fetch from SearXNG: HTTP Error 403 Forbidden
The SearXNG instance rejected the request, often due to misconfigured security settings, IP filtering, or user-agent restrictions, especially when requesting JSON output.
fix
Verify that your SearXNG instance is configured to accept requests from the `mcp-searxng` server, and that it allows JSON output. Check SearXNG's `settings.json` for security-related configurations like `allowed_hosts`, `allowed_users`, or `user_agent` requirements. Ensure no firewalls are blocking the requests.
TypeError: McpServer is not a constructor
Attempting to import `McpServer` using CommonJS `require()` syntax or an incorrect import path in an ESM environment, or the symbol is not a class constructor.
fix
Ensure you are using ECMAScript Modules (ESM) `import { McpServer } from 'mcp-searxng';` and that your `package.json` specifies `"type": "module"` or your file has a `.mjs` extension. Confirm `McpServer` is indeed a class and not a function or object.
Upgrade
Version history
0.1.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
OpenAI (training)
1
Resources
mcp-searxng — npm install mcp-searxng · libregistry