SearXNG MCP Server

Instructions

Implementation Reference

• src/index.ts:155-216 (registration)

  Tool registration in ListToolsRequestSchema handler, defining the searxngsearch tool with name, description, and input schema.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { // Define available tools const tools: Tool[] = [ { name: "searxngsearch", description: "Perform web searches using SearXNG, a privacy-respecting metasearch engine. Returns relevant web content with customizable parameters.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query" }, language: { type: "string", description: "Language code for search results (e.g., 'en', 'de', 'fr'). Default: 'en'", default: "en" }, time_range: { type: "string", enum: ["day", "week", "month", "year"], description: "Time range for search results. Options: 'day', 'week', 'month', 'year'. Default: null (no time restriction).", default: null }, categories: { type: "array", items: { type: "string" }, description: "Categories to search in (e.g., 'general', 'images', 'news'). Default: null (all categories).", default: null }, engines: { type: "array", items: { type: "string" }, description: "Specific search engines to use. Default: null (all available engines).", default: null }, safesearch: { type: "number", enum: [0, 1, 2], description: "Safe search level: 0 (off), 1 (moderate), 2 (strict). Default: 1 (moderate).", default: 1 }, pageno: { type: "number", description: "Page number for results. Must be minimum 1. Default: 1.", minimum: 1, default: 1 }, max_results: { type: "number", description: "Maximum number of search results to return. Range: 1-50. Default: 10.", default: 10, minimum: 1, maximum: 50 } }, required: ["query"] } } ]; return { tools }; });
• src/index.ts:162-212 (schema)

  Input schema for searxngsearch tool, specifying parameters like query (required), language, time_range, categories, engines, safesearch, pageno, and max_results with types, enums, defaults, and constraints.
  type: "object", properties: { query: { type: "string", description: "Search query" }, language: { type: "string", description: "Language code for search results (e.g., 'en', 'de', 'fr'). Default: 'en'", default: "en" }, time_range: { type: "string", enum: ["day", "week", "month", "year"], description: "Time range for search results. Options: 'day', 'week', 'month', 'year'. Default: null (no time restriction).", default: null }, categories: { type: "array", items: { type: "string" }, description: "Categories to search in (e.g., 'general', 'images', 'news'). Default: null (all categories).", default: null }, engines: { type: "array", items: { type: "string" }, description: "Specific search engines to use. Default: null (all available engines).", default: null }, safesearch: { type: "number", enum: [0, 1, 2], description: "Safe search level: 0 (off), 1 (moderate), 2 (strict). Default: 1 (moderate).", default: 1 }, pageno: { type: "number", description: "Page number for results. Must be minimum 1. Default: 1.", minimum: 1, default: 1 }, max_results: { type: "number", description: "Maximum number of search results to return. Range: 1-50. Default: 10.", default: 10, minimum: 1, maximum: 50 } }, required: ["query"] }
• src/index.ts:218-311 (handler)

  Core handler logic for executing searxngsearch: validates input, prepares parameters, calls SearXNG /search endpoint via axios, limits results, formats as JSON response, handles errors including auth and API failures.
  this.server.setRequestHandler(CallToolRequestSchema, async (request) => { try { if (request.params.name !== "searxngsearch") { throw new McpError( ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}` ); } const args = request.params.arguments ?? {}; // Validate required parameters if (!args.query || typeof args.query !== 'string') { throw new McpError( ErrorCode.InvalidParams, "Query parameter is required and must be a string" ); } // Prepare search parameters with defaults const searchParams: SearchParams = { q: args.query, format: 'json', language: typeof args.language === 'string' ? args.language : 'en', safesearch: typeof args.safesearch === 'number' ? args.safesearch : 1, pageno: typeof args.pageno === 'number' ? args.pageno : 1, }; // Add optional parameters if provided if (args.time_range && typeof args.time_range === 'string') searchParams.time_range = args.time_range; if (Array.isArray(args.categories)) searchParams.categories = args.categories; if (Array.isArray(args.engines)) searchParams.engines = args.engines; console.error(`[SearXNG] Searching for: ${args.query}`); // Make request to SearXNG const response = await this.axiosInstance.get('/search', { params: searchParams }); const searchResults: SearXNGResponse = response.data; // Limit results if max_results is specified const maxResults = typeof args.max_results === 'number' ? args.max_results : 10; const limitedResults = searchResults.results.slice(0, maxResults); // Construct a new response object with the limited results const finalResponse: SearXNGResponse = { ...searchResults, // Copy other fields like query, answers, suggestions etc. results: limitedResults, // Use the truncated results list number_of_results: limitedResults.length // Update the count to reflect the truncation }; // Return the modified JSON data return { content: [{ type: "text", text: JSON.stringify(finalResponse, null, 2) }] }; } catch (error: any) { console.error("[SearXNG Error]", error); if (axios.isAxiosError(error)) { // Handle authentication errors if (error.response?.status === 401) { return { content: [{ type: "text", text: "Authentication failed. Please check your SearXNG username and password." }], isError: true, }; } return { content: [{ type: "text", text: `SearXNG API error: ${error.response?.data?.message ?? error.message}` }], isError: true, }; } return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true, }; } }); }
• src/index.ts:28-70 (helper)

  Helper function to fetch public list of SearXNG instances and select a random standard (non-onion/hidden) instance for use when no SEARXNG_URL is provided.
  async function getRandomSearXNGInstance(): Promise<string> { try { console.error("[SearXNG] Fetching list of SearXNG instances..."); const response = await axios.get(INSTANCES_LIST_URL); const instancesData = parse(response.data); // Debug the structure console.error("[SearXNG] Instances data structure:", Object.keys(instancesData)); // Filter for standard internet instances (not onion or hidden) const standardInstances: string[] = []; // The instances.yml file has a structure where each key is a URL for (const [url, data] of Object.entries(instancesData)) { const instanceData = data as any; // Check if it's a standard instance (not hidden or onion) if ( instanceData && (!instanceData.comments || (!instanceData.comments.includes("hidden") && !instanceData.comments.includes("onion"))) && (!instanceData.network_type || instanceData.network_type === "normal") ) { standardInstances.push(url); } } console.error(`[SearXNG] Found ${standardInstances.length} standard instances`); if (standardInstances.length === 0) { throw new Error("No standard SearXNG instances found"); } // Select a random instance const randomInstance = standardInstances[Math.floor(Math.random() * standardInstances.length)]; console.error(`[SearXNG] Selected random instance: ${randomInstance}`); return randomInstance; } catch (error) { console.error("[SearXNG] Error fetching instances:", error); throw new Error("Failed to fetch SearXNG instances list"); } }