Brave Search MCP Server

Instructions

        Args:
            query: Search terms
            count: Desired number of results (10-20)
        

Implementation Reference

• src/server.py:133-166 (handler)

  The handler function for 'brave_web_search' tool, including the MCP registration decorator. It performs a web search using the Brave API, formats up to 20 results with title, description, URL, and extra snippets.

  @self.mcp.tool()
  async def brave_web_search(
      query: str,
      count: Optional[int] = 20
  ) -> str:
      """Execute web search using Brave Search API with improved results
      
      Args:
          query: Search terms
          count: Desired number of results (10-20)
      """
      min_results = max(10, min(count, 20))  # Ensure between 10 and 20
      
      all_results = await self._get_web_results(query, min_results)
      
      if not all_results:
          return "No results found for the query."
          
      formatted_results = []
      for result in all_results[:min_results]:
          formatted_result = [
              f"Title: {result.get('title', 'N/A')}",
              f"Description: {result.get('description', 'N/A')}",
              f"URL: {result.get('url', 'N/A')}"
          ]
          
          # Include additional context if available
          if result.get('extra_snippets'):
              formatted_result.append("Additional Context:")
              formatted_result.extend([f"- {snippet}" for snippet in result['extra_snippets'][:2]])
              
          formatted_results.append("\n".join(formatted_result))
      
      return "\n\n".join(formatted_results)

• src/server.py:71-102 (helper)

  Supporting helper method that makes the actual HTTP request to Brave's web/search API, handles rate limiting, and falls back on error 422 by reducing count.

  async def _get_web_results(self, query: str, min_results: int) -> List[Dict]:
      """Fetch web results with pagination until minimum count is reached"""
      client = self.get_client()
      self.rate_limit.check()
      
      try:
          # Make a single request with the maximum allowed count
          response = await client.get(
              f"{self.base_url}/web/search",
              params={
                  "q": query,
                  "count": min_results
              }
          )
          response.raise_for_status()
          data = response.json()
          results = data.get("web", {}).get("results", [])
          return results
      except httpx.HTTPStatusError as e:
          if e.response.status_code == 422:
              # If we get a 422, try with a smaller count
              response = await client.get(
                  f"{self.base_url}/web/search",
                  params={
                      "q": query,
                      "count": 10  # Fall back to smaller count
                  }
              )
              response.raise_for_status()
              data = response.json()
              return data.get("web", {}).get("results", [])
          raise  # Re-raise other HTTP errors

• src/server.py:57-57 (registration)

  Calls _setup_tools() in __init__ which defines and registers the tools including brave_web_search.

  self._setup_tools()

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

  Input schema defined by type hints and docstring in the handler function.

      query: str,
      count: Optional[int] = 20
  ) -> str:
      """Execute web search using Brave Search API with improved results
      
      Args:
          query: Search terms
          count: Desired number of results (10-20)