brave_place_search

Instructions

When to use:
    - Finding places near a set of coordinates or a named location (e.g. "coffee shops near me", "bookstores in Paris")
    - Browsing general points of interest in an area when no query is supplied
    - Building a place-finding experience that needs structured business data (hours, ratings, etc.)
    - Augmenting an answer with the location's address, phone number, or rating

Provide a search area via 'latitude' + 'longitude' or a 'location' string (or both). When neither is provided, a 'query' is expected. Use 'count' to keep responses small (max 50, default 20).

For US locations the recommended 'location' format is '<city> <state> <country name>' (e.g. 'san francisco ca united states'); for non-US locations use '<city> <country name>' (e.g. 'tokyo japan').

Implementation Reference

• src/tools/place_search/index.ts:34-51 (handler)

  The main handler function that validates inputs, calls the Brave API's issueRequest with 'placeSearch' endpoint, validates the response, and returns structured content.

  export const execute = async (params: QueryParams) => {
    const parsedParams = RequestParamsSchema.parse(params);
    const parsedHeaders = RequestHeadersSchema.parse(params);
  
    const response = await API.issueRequest<'placeSearch'>(
      'placeSearch',
      parsedParams,
      parsedHeaders
    );
    const parsed = PlaceSearchApiResponseSchema.safeParse(response);
    const payload = parsed.success ? parsed.data : response;
  
    return {
      content: [{ type: 'text', text: JSON.stringify(payload) } as TextContent],
      isError: false,
      structuredContent: payload,
    };
  };

• src/tools/place_search/index.ts:53-65 (registration)

  Registers the brave_place_search tool with the MCP server, linking its name, description, input/output schemas, and the execute handler.

  export const register = (mcpServer: McpServer) => {
    mcpServer.registerTool(
      name,
      {
        title: name,
        description: description,
        inputSchema: PlaceSearchInputSchema.shape,
        outputSchema: PlaceSearchApiResponseSchema.shape,
        annotations: annotations,
      },
      execute
    );
  };

• src/tools/place_search/schemas/input.ts:143-255 (schema)

  Input validation schemas including request parameters (query, radius, count, coordinates, location, country, language, units, safesearch, spellcheck, geoloc) and request headers (api-version, accept, cache-control, user-agent).

  export const RequestParamsSchema = z.object({
    query: z
      .string()
      .trim()
      .max(400)
      .refine(
        (str) => str.length === 0 || str.split(/\s+/).length <= 50,
        'Query cannot exceed 50 words'
      )
      .transform((str) => (str.length === 0 ? undefined : str))
      .describe(
        'Query string to search for points of interest in an area. If no query is provided, the endpoint will return general points of interest in the given area.'
      )
      .optional(),
    radius: z
      .number()
      .min(0)
      .describe(
        'Search radius around the supplied coordinates, in meters. If omitted, the search is performed globally.'
      )
      .optional(),
    count: z
      .number()
      .int()
      .min(1)
      .max(50)
      .describe('Number of results to return. Maximum is 50. Default is 20.')
      .optional(),
    latitude: z
      .number()
      .min(-90)
      .max(90)
      .describe(
        'Latitude of the geographical coordinates around which to search, in degrees (-90 to 90). Typically paired with `longitude`.'
      )
      .optional(),
    longitude: z
      .number()
      .min(-180)
      .max(180)
      .describe(
        'Longitude of the geographical coordinates around which to search, in degrees (-180 to 180). Typically paired with `latitude`.'
      )
      .optional(),
    location: z
      .string()
      .trim()
      .min(1)
      .describe(
        "Location string to search around, used as an alternative to `latitude` and `longitude`. For US locations prefer the form '<city> <state> <country name>' (e.g. 'san francisco ca united states'); for non-US locations use '<city> <country name>' (e.g. 'tokyo japan'). No commas or special characters needed; capitalization does not matter."
      )
      .optional(),
    country: CountryCodesSchema.describe(
      "Two-letter country code (ISO 3166-1 alpha-2) used to scope the search. Defaults to 'US'."
    ).optional(),
    search_lang: SearchLangCodesSchema.describe(
      "Language for the search results. Defaults to 'en'."
    ).optional(),
    ui_lang: UiLangCodesSchema.describe(
      "User interface language for the response, usually of the form '<language>-<region>'. Defaults to 'en-US'."
    ).optional(),
    units: z
      .enum(['metric', 'imperial'])
      .describe("Units of measurement for distance values. Defaults to 'metric'.")
      .optional(),
    safesearch: z
      .enum(['off', 'moderate', 'strict'])
      .describe(
        "Safe search level for the query results. 'off' - No filtering. 'moderate' - Filter out explicit content. 'strict' - Filter out explicit and suggestive content. Defaults to 'strict'."
      )
      .optional(),
    spellcheck: z
      .boolean()
      .describe('Whether to apply spellcheck before executing the search. Defaults to true.')
      .optional(),
    geoloc: z.string().describe('Optional geolocation token used to refine results.').optional(),
  });
  
  export const RequestHeadersSchema = z.object({
    'api-version': z
      .string()
      .regex(/^\d{4}-\d{2}-\d{2}$/)
      .describe(
        'The API version to use. This is denoted by the format YYYY-MM-DD. Default is the latest that is available. Read more about API versioning at https://api-dashboard.search.brave.com/documentation/guides/versioning.'
      )
      .optional(),
    accept: z
      .enum(['application/json', '*/*'])
      .describe('The default supported media type is application/json.')
      .optional(),
    'cache-control': z
      .literal('no-cache')
      .describe(
        'Brave Search will return cached content by default. To prevent caching set the Cache-Control header to no-cache. This is currently done as best effort.'
      )
      .optional(),
    'user-agent': z
      .string()
      .describe(
        'The user agent originating the request. Brave Search can utilize the user agent to provide a different experience depending on the device as described by the string. The user agent should follow the commonly used browser agent strings on each platform. For more information on curating user agents, see RFC 9110.'
      )
      .optional(),
  });
  
  export const PlaceSearchInputSchema = z.object({
    ...RequestParamsSchema.shape,
    ...RequestHeadersSchema.shape,
  });
  
  export type PlaceSearchInput = z.input<typeof PlaceSearchInputSchema>;
  export type PlaceSearchQueryParams = z.infer<typeof RequestParamsSchema>;
  export type PlaceSearchRequestHeaders = z.infer<typeof RequestHeadersSchema>;

• src/tools/place_search/schemas/output.ts:231-245 (schema)

  Output response schema defining the structure of the place search API response, including query metadata, array of POI results (with title, coordinates, address, opening hours, contact, rating, reviews, pictures, categories, timezone, etc.), and resolved location info.

  export const PlaceSearchApiResponseSchema = z.looseObject({
    type: z
      .literal('locations')
      .describe('Top-level response discriminator. Always "locations" for Place Search.'),
    query: QuerySchema.optional(),
    results: z
      .array(ResultSchema)
      .describe('Array of points-of-interest matching the search.')
      .optional(),
    location: LocationSchema.describe(
      'The resolved search-area metadata, when available.'
    ).optional(),
  });
  
  export type PlaceSearchApiResponse = z.infer<typeof PlaceSearchApiResponseSchema>;

• src/BraveAPI/index.ts:44-142 (helper)

  The generic API request helper that routes 'placeSearch' to /res/v1/local/place_search, constructs query parameters and headers, fetches from Brave Search API, handles errors, and returns the typed response.

  async function issueRequest<T extends keyof Endpoints>(
    endpoint: T,
    parameters: Endpoints[T]['params'],
    requestHeaders: Endpoints[T]['requestHeaders'] = {} as Endpoints[T]['requestHeaders']
  ): Promise<Endpoints[T]['response']> {
    // TODO (Sampson): Improve rate-limit logic to support self-throttling and n-keys
    // checkRateLimit();
  
    // Determine URL, and setup parameters
    const url = new URL(`https://api.search.brave.com${typeToPathMap[endpoint]}`);
    const queryParams = new URLSearchParams();
  
    // TODO (Sampson): Move param-construction/validation to modules
    for (const [key, value] of Object.entries(parameters)) {
      // The 'ids' parameter is expected to appear multiple times for multiple IDs
      if (['localPois', 'localDescriptions'].includes(endpoint)) {
        if (key === 'ids') {
          if (Array.isArray(value) && value.length > 0) {
            value.forEach((id) => queryParams.append(key, id));
          } else if (typeof value === 'string') {
            queryParams.set(key, value);
          }
  
          continue;
        }
      }
  
      // Handle `result_filter` parameter
      if (key === 'result_filter') {
        /**
         * Handle special behavior of 'summary' parameter:
         * When 'summary' is true, we need to either set result_filter to
         * 'summarizer', or leave it excluded entirely. This is due to a known
         * bug in the now-deprecated Summarizer endpoint. Setting it to
         * 'summarizer' will result in no web results being returned, which is
         * not ideal. As such, we skip the parameter entirely.
         * See https://github.com/brave/brave-search-mcp-server/issues/272 and
         * https://bravesoftware.slack.com/archives/C01NNFM9XMM/p1751654841090929
         */
        if ('summary' in parameters && parameters.summary === true) {
          continue;
        } else if (Array.isArray(value) && value.length > 0) {
          queryParams.set(key, value.join(','));
        }
  
        continue;
      }
  
      // Handle `goggles` parameter(s)
      if (key === 'goggles') {
        const candidates = Array.isArray(value) ? value : [value];
        for (const candidate of candidates) {
          const normalized = normalizeGoggle(candidate);
          if (normalized !== null) {
            queryParams.append(key, normalized);
          }
        }
        continue;
      }
  
      if (value !== undefined && value !== null) {
        queryParams.set(key === 'query' ? 'q' : key, value.toString());
      }
    }
  
    // Issue Request
    const urlWithParams = url.toString() + '?' + queryParams.toString();
    const headers = new Headers(getDefaultRequestHeaders());
    for (const [key, value] of Object.entries(requestHeaders)) {
      if (value === undefined || value === null) continue;
      headers.set(key, String(value));
    }
  
    const response = await fetch(urlWithParams, { headers });
  
    // Handle Error
    if (!response.ok) {
      let errorMessage = `${response.status} ${response.statusText}`;
  
      try {
        const responseBody = await response.json();
        errorMessage += `\n${stringify(responseBody, true)}`;
      } catch (error) {
        errorMessage += `\n${await response.text()}`;
      }
  
      // TODO (Sampson): Setup proper error handling, updating state, etc.
      throw new Error(errorMessage);
    }
  
    // Return Response
    const responseBody = await response.json();
  
    return responseBody as Endpoints[T]['response'];
  }
  
  export default {
    issueRequest,
  };