SearXNG MCP Server

Instructions

Implementation Reference

• src/searxng_mcp/tools/search.py:129-172 (handler)

  The core handler function implementing the search_media tool logic. It queries the SearXNG API with the specified media category (images/videos), processes the results, and formats them into a markdown-style TextContent response.

  def search_media(
      self,
      query: str,
      media_type: Literal["images", "videos"] = "images",
      engines: Optional[str] = None,
      max_results: int = 10
  ) -> List[TextContent]:
      """Search for images or videos.
  
      Args:
          query: Search query
          media_type: "images" or "videos"
          engines: Comma-separated engine list
          max_results: Maximum results to return
  
      Returns:
          Formatted media search results
      """
      results = self._search(query, category=media_type, engines=engines)
  
      if media_type == "images":
          output = f"🖼️ Image 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"   URL: {result.get('img_src', 'N/A')}\n"
              output += f"   Source: {result.get('url', 'N/A')}\n"
              if result.get('thumbnail_src'):
                  output += f"   Thumbnail: {result['thumbnail_src']}\n"
              output += "\n"
      else:  # videos
          output = f"🎥 Video 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'):
                  output += f"   {result['content']}\n"
              if result.get('publishedDate'):
                  output += f"   Published: {result['publishedDate']}\n"
              output += "\n"
  
      if not results.get("results"):
          output += f"No {media_type} found.\n"
  
      return [TextContent(type="text", text=output)]

• src/searxng_mcp/server.py:149-156 (registration)

  MCP tool registration for search_media using FastMCP decorator, including input schema via Annotated Fields. Delegates execution to the SearchTools instance.

  @self.mcp.tool(description=SEARCH_MEDIA_DESC)
  def search_media(
      query: Annotated[str, Field(description="Media search query")],
      media_type: Annotated[Literal["images", "videos"], Field(description="Type of media")] = "images",
      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_media(query, media_type, engines, max_results)

• src/searxng_mcp/server.py:32-45 (schema)

  Tool description string providing usage guidelines, parameters, and return format for the search_media tool.

  SEARCH_MEDIA_DESC = """Search for images or videos.
  
  Use this when:
  - User wants to find images or photos
  - Looking for video content
  - "show me pictures of..." or "find videos about..."
  
  Parameters:
  query* - What to find
  media_type - "images" or "videos" (default: images)
  engines - Optional: Specific engines
  max_results - Number of results (default: 10, max: 50)
  
  Returns: Media URLs with thumbnails and sources"""