SearXNG MCP Server

Instructions

Implementation Reference

• src/searxng_mcp_server/server.py:215-229 (handler)

  MCP server tool handler for get_suggestions: extracts arguments, calls client.get_suggestions, formats and returns JSON response as TextContent

  elif name == "get_suggestions":
      suggestions = await client.get_suggestions(
          query=arguments["query"],
          language=arguments.get("language", "en"),
      )
  
      return [
          TextContent(
              type="text",
              text=json.dumps(
                  {"query": arguments["query"], "suggestions": suggestions},
                  indent=2,
              ),
          )
      ]

• src/searxng_mcp_server/client.py:133-162 (helper)

  SearXNGClient.get_suggestions: makes HTTP GET to /autocomplete endpoint with query and language params, returns list of suggestions from JSON response

  async def get_suggestions(
      self,
      query: str,
      language: str = "en",
  ) -> List[str]:
      """Get search suggestions for a query prefix.
  
      Args:
          query: The query prefix
          language: Language code for suggestions
  
      Returns:
          List of suggestion strings
  
      Raises:
          httpx.HTTPError: If the request fails
      """
      url = urljoin(self.base_url, "/autocomplete")
  
      params = {
          "q": query,
          "language": language,
      }
  
      response = await self.client.get(url, params=params)
      response.raise_for_status()
  
      # Autocomplete returns a simple list
      return response.json()

• src/searxng_mcp_server/server.py:107-135 (registration)

  Registration of get_suggestions tool in list_tools(): defines name, description, and inputSchema

                  Tool(
                      name="get_suggestions",
                      description="""Get search suggestions/autocomplete for a query prefix.
                      
  This tool provides search suggestions based on a partial query, similar to autocomplete
  functionality in search engines. Useful for discovering related searches or expanding
  on a topic.
  
  Use this when you need to:
  - Get autocomplete suggestions for a search
  - Discover related search terms
  - Help users formulate better search queries
  - Explore variations of a search topic""",
                      inputSchema={
                          "type": "object",
                          "properties": {
                              "query": {
                                  "type": "string",
                                  "description": "The query prefix to get suggestions for",
                              },
                              "language": {
                                  "type": "string",
                                  "description": "Language code for suggestions (default: 'en')",
                                  "default": "en",
                              },
                          },
                          "required": ["query"],
                      },
                  ),

• src/searxng_mcp_server/server.py:120-134 (schema)

  Input schema definition for get_suggestions tool: requires 'query', optional 'language' with defaults

  inputSchema={
      "type": "object",
      "properties": {
          "query": {
              "type": "string",
              "description": "The query prefix to get suggestions for",
          },
          "language": {
              "type": "string",
              "description": "Language code for suggestions (default: 'en')",
              "default": "en",
          },
      },
      "required": ["query"],
  },