SearXNG MCP Server

Instructions

Implementation Reference

• src/searxng_mcp_server/server.py:49-106 (registration)

  Registration of the 'search' tool including its name, description, and input schema in the list_tools handler.
  Tool( name="search", description="""Search the web using SearXNG search engine. This tool performs web searches across multiple search engines aggregated by SearXNG. You can filter by categories (general, images, videos, news, etc.), specific engines, language, and time range. Returns comprehensive results including titles, URLs, content snippets, and metadata. Use this when you need to: - Search for information on the web - Find recent news or articles - Search for images or videos - Get diverse results from multiple search engines - Research a topic across different sources""", inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "The search query string", }, "categories": { "type": "array", "items": {"type": "string"}, "description": "List of categories to search (e.g., ['general', 'images', 'news']). Available: general, images, videos, news, music, files, social media, science, it, map", }, "engines": { "type": "array", "items": {"type": "string"}, "description": "List of specific search engines to use (e.g., ['google', 'bing', 'duckduckgo'])", }, "language": { "type": "string", "description": "Language code for results (default: 'en')", "default": "en", }, "page": { "type": "integer", "description": "Page number for pagination (default: 1)", "default": 1, "minimum": 1, }, "time_range": { "type": "string", "enum": ["day", "month", "year"], "description": "Time range filter for results", }, "safesearch": { "type": "integer", "enum": [0, 1, 2], "description": "Safe search level: 0=off, 1=moderate, 2=strict (default: 0)", "default": 0, }, }, "required": ["query"], }, ),
• src/searxng_mcp_server/server.py:179-213 (handler)

  The handler logic within call_tool that executes the 'search' tool: calls SearXNGClient.search, formats results, and returns as TextContent.
  if name == "search": response = await client.search( query=arguments["query"], categories=arguments.get("categories"), engines=arguments.get("engines"), language=arguments.get("language", "en"), page=arguments.get("page", 1), time_range=arguments.get("time_range"), safesearch=arguments.get("safesearch", 0), ) # Format results for better readability formatted_results = { "query": response.query, "number_of_results": response.number_of_results, "results": [ { "title": r.title, "url": r.url, "content": r.content, "engine": r.engine, "score": r.score, } for r in response.results ], "suggestions": response.suggestions, "answers": response.answers, } return [ TextContent( type="text", text=json.dumps(formatted_results, indent=2), ) ]
• src/searxng_mcp_server/server.py:64-104 (schema)

  Input schema definition for the 'search' tool, specifying parameters like query, categories, engines, etc.
  inputSchema={ "type": "object", "properties": { "query": { "type": "string", "description": "The search query string", }, "categories": { "type": "array", "items": {"type": "string"}, "description": "List of categories to search (e.g., ['general', 'images', 'news']). Available: general, images, videos, news, music, files, social media, science, it, map", }, "engines": { "type": "array", "items": {"type": "string"}, "description": "List of specific search engines to use (e.g., ['google', 'bing', 'duckduckgo'])", }, "language": { "type": "string", "description": "Language code for results (default: 'en')", "default": "en", }, "page": { "type": "integer", "description": "Page number for pagination (default: 1)", "default": 1, "minimum": 1, }, "time_range": { "type": "string", "enum": ["day", "month", "year"], "description": "Time range filter for results", }, "safesearch": { "type": "integer", "enum": [0, 1, 2], "description": "Safe search level: 0=off, 1=moderate, 2=strict (default: 0)", "default": 0, }, }, "required": ["query"],
• src/searxng_mcp_server/client.py:81-132 (helper)

  Core search implementation in SearXNGClient that performs HTTP request to SearXNG /search endpoint and parses response.
  async def search( self, query: str, categories: Optional[List[str]] = None, engines: Optional[List[str]] = None, language: str = "en", page: int = 1, time_range: Optional[str] = None, safesearch: int = 0, format: str = "json", ) -> SearchResponse: """Perform a search query on SearXNG. Args: query: The search query string categories: List of categories to search (e.g., ["general", "images"]) engines: List of specific engines to use language: Language code for results (default: "en") page: Page number for pagination (default: 1) time_range: Time range filter ("day", "month", "year") safesearch: Safe search level (0=off, 1=moderate, 2=strict) format: Response format (default: "json") Returns: SearchResponse containing search results Raises: httpx.HTTPError: If the request fails """ url = urljoin(self.base_url, "/search") params: Dict[str, Any] = { "q": query, "format": format, "language": language, "pageno": page, "safesearch": safesearch, } if categories: params["categories"] = ",".join(categories) if engines: params["engines"] = ",".join(engines) if time_range: params["time_range"] = time_range response = await self.client.get(url, params=params) response.raise_for_status() data = response.json() return SearchResponse(**data)
• src/searxng_mcp_server/client.py:23-33 (schema)

  Pydantic model defining the structure of SearXNG search response used in the tool.
  class SearchResponse(BaseModel): """Response from SearXNG search API.""" query: str number_of_results: int = Field(alias="number_of_results") results: List[SearchResult] suggestions: List[str] = [] answers: List[Any] = [] # Can be strings or dicts infoboxes: List[Dict[str, Any]] = [] unresponsive_engines: List[str] = []