Brave Search MCP Server

Instructions

Implementation Reference

• src/server.py:168-224 (handler)

  Main handler for the 'brave_local_search' tool. Decorated with @self.mcp.tool() for registration. Implements local business search logic: queries Brave API for locations, paginates if needed, fetches POI/details, formats output, falls back to web search.
  @self.mcp.tool() async def brave_local_search( query: str, count: Optional[int] = 20 # Changed default from 5 to 20 ) -> str: """Search for local businesses and places Args: query: Location terms count: Results (1-20 """ self.rate_limit.check() # Initial location search params = { "q": query, "search_lang": "en", "result_filter": "locations", "count": 20 # Always request maximum results } client = self.get_client() response = await client.get( f"{self.base_url}/web/search", params=params ) response.raise_for_status() data = response.json() location_ids = self._extract_location_ids(data) if not location_ids: # If no local results found, fallback to web search # with minimum 10 results return await brave_web_search(query, 20) # If we have less than 10 location IDs, try to get more offset = 0 while len(location_ids) < 10 and offset < 40: offset += 20 additional_response = await client.get( f"{self.base_url}/web/search", params={ "q": query, "search_lang": "en", "result_filter": "locations", "count": 20, "offset": offset } ) additional_data = additional_response.json() location_ids.extend(self._extract_location_ids(additional_data)) # Get details for at least 10 locations pois, descriptions = await self._get_location_details( location_ids[:max(10, len(location_ids))] ) return self._format_local_results(pois, descriptions)
• src/server.py:226-245 (helper)

  Helper function to fetch detailed POI (points of interest) and description data for location IDs using parallel asyncio.gather calls to Brave API.
  async def _get_location_details( self, ids: List[str] ) -> Tuple[Dict[str, Any], Dict[str, Any]]: """Fetch POI and description data for locations""" client = self.get_client() pois_response, desc_response = await asyncio.gather( client.get( f"{self.base_url}/local/pois", params={"ids": ids} ), client.get( f"{self.base_url}/local/descriptions", params={"ids": ids} ) ) return ( pois_response.json(), desc_response.json() )
• src/server.py:247-253 (helper)

  Helper to extract location IDs from the initial web search response filtered by 'locations'.
  def _extract_location_ids(self, data: Dict) -> List[str]: """Extract location IDs from search response""" return [ result["id"] for result in data.get("locations", {}).get("results", []) if "id" in result ]
• src/server.py:255-284 (helper)

  Helper to format the retrieved POI data and descriptions into a readable multi-line string output separated by ---.
  def _format_local_results( self, pois: Dict[str, Any], descriptions: Dict[str, Any] ) -> str: """Format local search results with details""" results = [] for poi in pois.get("results", []): location = { "name": poi.get("name", "N/A"), "address": self._format_address(poi.get("address", {})), "phone": poi.get("phone", "N/A"), "rating": self._format_rating(poi.get("rating", {})), "price": poi.get("priceRange", "N/A"), "hours": ", ".join(poi.get("openingHours", [])) or "N/A", "description": descriptions.get("descriptions", {}).get( poi["id"], "No description available" ) } results.append( f"Name: {location['name']}\n" f"Address: {location['address']}\n" f"Phone: {location['phone']}\n" f"Rating: {location['rating']}\n" f"Price Range: {location['price']}\n" f"Hours: {location['hours']}\n" f"Description: {location['description']}" )
• src/server.py:287-295 (helper)

  Helper utility to format address dictionary into a comma-separated string.
  def _format_address(self, addr: Dict) -> str: """Format address components""" components = [ addr.get("streetAddress", ""), addr.get("addressLocality", ""), addr.get("addressRegion", ""), addr.get("postalCode", "") ] return ", ".join(filter(None, components)) or "N/A"