MCP SearxNG Search

Instructions

Implementation Reference

• src/mcp_searxng_search/server.py:18-69 (handler)

  The main handler function for the 'searxng_search' tool. It performs a POST request to the SearxNG search endpoint, parses the HTML results using BeautifulSoup, extracts title, URL, and content snippet for up to max_results items, and returns them as a list of dicts. Includes input validation and comprehensive error handling with McpError.
  @mcp.tool() def searxng_search(query: str, max_results: int = 30) -> List[Dict[str, str]]: """ Searches the web using a SearxNG instance and returns a list of results. Args: query: The search query. max_results: The maximum number of results to return. Defaults to 30. Returns: A list of dictionaries, where each dictionary represents a search result and contains the title, URL, and content snippet. Returns an error message in a dictionary if the search fails. """ if max_results <= 0: raise McpError(ErrorData(INVALID_PARAMS, "max_results must be greater than 0.")) search_url = f"{SEARXNG_BASE_URL}/search" headers = { 'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7', 'Accept-Language': 'en-US,en;q=0.9', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'Content-Type': 'application/x-www-form-urlencoded', 'Pragma': 'no-cache', 'Upgrade-Insecure-Requests': '1', 'User-Agent': USER_AGENT } data = f"q={query}&categories=general&language=auto&time_range=&safesearch=0&theme=simple" try: response = requests.post(search_url, headers=headers, data=data, verify=False, timeout=30) response.raise_for_status() # Raise HTTPError for bad responses (4xx or 5xx) html_content = response.text soup = BeautifulSoup(html_content, 'html.parser') results = [] for article in soup.find_all('article', class_='result')[:max_results]: url_header = article.find('a', class_='url_header') if url_header: url = url_header['href'] title = article.find('h3').text.strip() if article.find('h3') else "No Title" description = article.find('p', class_='content').text.strip() if article.find('p', class_='content') else "No Description" results.append({ 'title': title, 'url': url, 'content': description }) return results except requests.exceptions.RequestException as e: raise McpError(ErrorData(INTERNAL_ERROR, f"Error during search: {str(e)}")) except Exception as e: raise McpError(ErrorData(INTERNAL_ERROR, f"Unexpected error: {str(e)}"))
• src/mcp_searxng_search/__init__.py:10-10 (registration)

  Registers and starts the MCP server instance (imported from server.py), making the 'searxng_search' tool available over the Model Context Protocol.
  mcp.run()
• src/mcp_searxng_search/server.py:9-9 (registration)

  Creates the FastMCP server instance named 'searxng' to which the tool is registered via the @mcp.tool() decorator.
  mcp = FastMCP("searxng")
• src/mcp_searxng_search/server.py:19-31 (schema)

  The function signature and docstring defining the input schema (query: str, optional max_results: int=30) and output schema (List[Dict[str, str]] with keys 'title', 'url', 'content').
  def searxng_search(query: str, max_results: int = 30) -> List[Dict[str, str]]: """ Searches the web using a SearxNG instance and returns a list of results. Args: query: The search query. max_results: The maximum number of results to return. Defaults to 30. Returns: A list of dictionaries, where each dictionary represents a search result and contains the title, URL, and content snippet. Returns an error message in a dictionary if the search fails. """