SearXNG MCP Server

Instructions

Implementation Reference

• src/searxng_mcp/tools/search.py:89-127 (handler)

  Core handler function for the 'search' tool that queries SearXNG via _search, formats and truncates results, and returns as List[TextContent].

  def search(
      self,
      query: str,
      category: Literal["general", "news"] = "general",
      engines: Optional[str] = None,
      max_results: int = 10
  ) -> List[TextContent]:
      """Quick search for web or news.
  
      Args:
          query: Search query
          category: "general" for web search, "news" for news
          engines: Comma-separated engine list (e.g., "google,bing,brave")
          max_results: Maximum results to return
  
      Returns:
          Formatted search results
      """
      results = self._search(query, category=category, engines=engines)
  
      if category == "news":
          output = f"📰 News Results for: {query}\n\n"
      else:
          output = f"🔍 Search Results for: {query}\n\n"
  
      for i, result in enumerate(results.get("results", [])[:max_results], 1):
          output += f"{i}. **{result.get('title', 'No title')}**\n"
          output += f"   {result.get('url', '')}\n"
          if result.get('content'):
              content = result['content'][:200] + "..." if len(result['content']) > 200 else result['content']
              output += f"   {content}\n"
          if category == "news" and result.get('publishedDate'):
              output += f"   📅 {result['publishedDate']}\n"
          output += "\n"
  
      if not results.get("results"):
          output += "No results found.\n"
  
      return [TextContent(type="text", text=output)]

• src/searxng_mcp/server.py:140-148 (registration)

  Registers the 'search' tool with the MCP server using FastMCP.tool decorator, defines input schema with Pydantic Field validations, and delegates execution to SearchTools.search instance method.

  @self.mcp.tool(description=SEARCH_DESC)
  def search(
      query: Annotated[str, Field(description="Search query")],
      category: Annotated[Literal["general", "news"], Field(description="Search category")] = "general",
      engines: Annotated[Optional[str], Field(description="Comma-separated engine list")] = None,
      max_results: Annotated[int, Field(description="Maximum results", ge=1, le=50)] = 10
  ):
      return self.search_tools.search(query, category, engines, max_results)

• src/searxng_mcp/tools/search.py:23-68 (helper)

  Internal helper method that constructs SearXNG API request parameters and performs HTTP GET to fetch raw JSON search results.

  def _search(
      self,
      query: str,
      category: Optional[str] = None,
      engines: Optional[str] = None,
      language: str = "en",
      page: int = 1
  ) -> Dict[str, Any]:
      """Internal search method.
  
      Args:
          query: Search query
          category: Search category (general, images, videos, news, etc.)
          engines: Comma-separated list of engines
          language: Search language
          page: Page number
  
      Returns:
          Search results from SearXNG
      """
      params = {
          "q": query,
          "format": "json",
          "language": language,
          "pageno": page
      }
  
      if category:
          params["categories"] = category
  
      if engines:
          params["engines"] = engines
  
      try:
          self.logger.info(f"Searching: {query} (category: {category})")
          response = requests.get(
              f"{self.searxng_url}/search",
              params=params,
              timeout=self.timeout
          )
          response.raise_for_status()
          return response.json()
      except Exception as e:
          self.logger.error(f"Search failed: {e}")
          raise RuntimeError(f"Search failed: {e}")

• src/searxng_mcp/server.py:142-145 (schema)

  Input schema definition for the 'search' tool using Pydantic's Annotated and Field for validation, descriptions, constraints (e.g., max_results 1-50). Note: this overlaps with registration block.

  query: Annotated[str, Field(description="Search query")],
  category: Annotated[Literal["general", "news"], Field(description="Search category")] = "general",
  engines: Annotated[Optional[str], Field(description="Comma-separated engine list")] = None,
  max_results: Annotated[int, Field(description="Maximum results", ge=1, le=50)] = 10