SearXNG MCP Server

Instructions

Input Schema

Input Schema (JSON Schema)

Implementation Reference

• src/searxng_mcp_server/client.py:81-132 (handler)

  Core handler implementation: the `search` method in `SearXNGClient` that executes the HTTP request to SearXNG's `/search` endpoint with parameters, parses JSON response into `SearchResponse` model.
  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/server.py:179-213 (handler)

  MCP tool dispatch handler in `call_tool`: handles 'search' tool call by invoking `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:49-106 (registration)

  Tool registration: defines the 'search' tool in `list_tools()` with name, description, and inputSchema, returned by the MCP server.
  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:64-105 (schema)

  Input schema definition for the 'search' tool, specifying parameters like query, categories, engines, etc., with types, descriptions, defaults, and requirements.
  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:23-33 (helper)

  Pydantic model for parsing SearXNG search API response, used in the handler.
  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] = []