@brave/brave-search-mcp-server 1.3.1

package/dist/tools/images/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/index.js

@@ -0,0 +1,14 @@
+import WebSearchTool from './web/index.js';
+import LocalSearchTool from './local/index.js';
+import VideoSearchTool from './videos/index.js';
+import ImageSearchTool from './images/index.js';
+import NewsSearchTool from './news/index.js';
+import SummarizerTool from './summarizer/index.js';
+export default {
+    WebSearchTool,
+    LocalSearchTool,
+    VideoSearchTool,
+    ImageSearchTool,
+    NewsSearchTool,
+    SummarizerTool,
+};

package/dist/tools/local/index.js

@@ -0,0 +1,136 @@
+import webParams from '../web/params.js';
+import API from '../../BraveAPI/index.js';
+import { formatWebResults } from '../web/index.js';
+import { stringify } from '../../utils.js';
+export const name = 'brave_local_search';
+export const annotations = {
+    title: 'Brave Local Search',
+    openWorldHint: true,
+};
+export const description = `
+    Brave Local Search API provides enrichments for location search results. Access to this API is available only through the Brave Search API Pro plans; confirm the user's plan before using this tool (if the user does not have a Pro plan, use the brave_web_search tool). Searches for local businesses and places using Brave's Local Search API. Best for queries related to physical locations, businesses, restaurants, services, etc.
+    
+    Returns detailed information including:
+        - Business names and addresses
+        - Ratings and review counts
+        - Phone numbers and opening hours
+
+    Use this when the query implies 'near me', 'in my area', or mentions specific locations (e.g., 'in San Francisco'). This tool automatically falls back to brave_web_search if no local results are found.
+`;
+// Access to Local API is available through the Pro plans.
+export const execute = async (params) => {
+    // Make sure both 'web' and 'locations' are in the result_filter
+    params = { ...params, result_filter: [...(params.result_filter || []), 'web', 'locations'] };
+    // Starts with a web search to retrieve potential location IDs
+    const { locations, web: web_fallback } = await API.issueRequest('web', params);
+    // We can send up to 20 location IDs at a time to the Local API
+    // TODO (Sampson): Add support for multiple requests
+    const locationIDs = (locations?.results || []).map((poi) => poi.id).slice(0, 20);
+    // No locations were found - user's plan may not include access to the Local API
+    if (!locations || locationIDs.length === 0) {
+        // If we have web results, but no locations, we'll fall back to the web results
+        if (web_fallback && web_fallback.results.length > 0) {
+            return buildFallbackWebResponse(web_fallback);
+        }
+        // If we have no web results, we'll send a message to the user
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: "No location data was returned. User's plan does not support local search, or the query may be unclear.",
+                },
+            ],
+        };
+    }
+    // Fetch AI-generated descriptions
+    const descriptions = await API.issueRequest('localDescriptions', {
+        ids: locationIDs,
+    });
+    return {
+        content: formatLocalResults(locations.results, descriptions.results).map((formattedPOI) => ({
+            type: 'text',
+            text: formattedPOI,
+        })),
+    };
+};
+const buildFallbackWebResponse = (web_fallback) => {
+    if (!web_fallback || web_fallback.results.length === 0)
+        throw new Error('No web results found');
+    const fallback = {
+        content: [
+            {
+                type: 'text',
+                text: "No location data was returned. Either the user's plan does not support local search, or the API was unable to find locations for the provided query. Falling back to general web search.",
+            },
+        ],
+    };
+    for (const web_result of formatWebResults(web_fallback)) {
+        fallback.content.push({
+            type: 'text',
+            text: stringify(web_result),
+        });
+    }
+    return fallback;
+};
+const formatLocalResults = (poisData, descData = []) => {
+    return poisData.map((poi) => {
+        return stringify({
+            name: poi.title,
+            price_range: poi.price_range,
+            phone: poi.contact?.telephone,
+            rating: poi.rating?.ratingValue,
+            hours: formatOpeningHours(poi.opening_hours),
+            rating_count: poi.rating?.reviewCount,
+            description: descData.find(({ id }) => id === poi.id)?.description,
+            address: poi.postal_address?.displayAddress,
+        });
+    });
+};
+const formatOpeningHours = (openingHours) => {
+    if (!openingHours)
+        return undefined;
+    /**
+     * Response will be something like {
+     *     'sunday': '10:00-18:00',
+     *     'monday': '10:00-18:00',
+     *     'tuesday': '10:00-18:00',
+     *     'wednesday': '10:00-18:00, 19:00-22:00',
+     *     'thursday': '10:00-18:00',
+     *     'friday': '10:00-18:00',
+     *     'saturday': '12:00-18:00',
+     * }
+     */
+    const today = openingHours.current_day || [];
+    const response = {};
+    const dayHours = [
+        [
+            `today (${today[0].full_name.toLowerCase()})`,
+            today.map(({ opens, closes }) => `${opens}-${closes}`),
+        ],
+    ];
+    // Add the rest of the days to the response
+    for (let parts of openingHours.days || []) {
+        // Not all days have arrays of hours, so normalize to an array
+        if (!Array.isArray(parts))
+            parts = [parts];
+        // Add the hours for each day to the response
+        for (const { full_name, opens, closes } of parts) {
+            const dayName = full_name.toLowerCase();
+            const existingEntry = dayHours.find(([name]) => name === dayName);
+            existingEntry
+                ? existingEntry[1].push(`${opens}-${closes}`)
+                : dayHours.push([dayName, [`${opens}-${closes}`]]);
+        }
+    }
+    for (const [name, hours] of dayHours) {
+        response[name] = hours.join(', ');
+    }
+    return response;
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: webParams.shape,
+    execute,
+};

package/dist/tools/local/params.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const LocalPoisParams = z.object({
+    ids: z.array(z.string()).describe('List of location IDs for which to fetch POIs'),
+});
+export const LocalDescriptionsParams = z.object({
+    ids: z.array(z.string()).describe('List of location IDs for which to fetch descriptions'),
+});

package/dist/tools/local/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/news/index.js

@@ -0,0 +1,53 @@
+import params from './params.js';
+import API from '../../BraveAPI/index.js';
+import { stringify } from '../../utils.js';
+export const name = 'brave_news_search';
+export const annotations = {
+    title: 'Brave News Search',
+    openWorldHint: true,
+};
+export const description = `
+    This tool searches for news articles using Brave's News Search API based on the user's query. Use it when you need current news information, breaking news updates, or articles about specific topics, events, or entities.
+    
+    When to use:
+        - Finding recent news articles on specific topics
+        - Getting breaking news updates
+        - Researching current events or trending stories
+        - Gathering news sources and headlines for analysis
+
+    Returns a JSON list of news-related results with title, url, and description. Some results may contain snippets of text from the article.
+    
+    When relaying results in markdown-supporting environments, always cite sources with hyperlinks.
+    
+    Examples:
+        - "According to [Reuters](https://www.reuters.com/technology/china-bans/), China bans uncertified and recalled power banks on planes".
+        - "The [New York Times](https://www.nytimes.com/2025/06/27/us/technology/ev-sales.html) reports that Tesla's EV sales have increased by 20%".
+        - "According to [BBC News](https://www.bbc.com/news/world-europe-65910000), the UK government has announced a new policy to support renewable energy".
+`;
+export const execute = async (params) => {
+    const response = await API.issueRequest('news', params);
+    return {
+        content: response.results.map((newsResult) => {
+            return {
+                type: 'text',
+                text: stringify({
+                    url: newsResult.url,
+                    title: newsResult.title,
+                    age: newsResult.age,
+                    page_age: newsResult.page_age,
+                    breaking: newsResult.breaking ?? false,
+                    description: newsResult.description,
+                    extra_snippets: newsResult.extra_snippets,
+                    thumbnail: newsResult.thumbnail?.src,
+                }),
+            };
+        }),
+    };
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: params.shape,
+    execute,
+};

package/dist/tools/news/params.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+export const params = z.object({
+    query: z
+        .string()
+        .max(400)
+        .refine((str) => str.split(/\s+/).length <= 50, 'Query cannot exceed 50 words')
+        .describe('Search query (max 400 chars, 50 words)'),
+    country: z
+        .string()
+        .default('US')
+        .describe('Search query country, where the results come from. The country string is limited to 2 character country codes of supported countries.')
+        .optional(),
+    search_lang: z
+        .string()
+        .default('en')
+        .describe('Search language preference. The 2 or more character language code for which the search results are provided.')
+        .optional(),
+    ui_lang: z
+        .string()
+        .default('en-US')
+        .describe('User interface language preferred in response. Usually of the format <language_code>-<country_code>. For more, see RFC 9110.')
+        .optional(),
+    count: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(20)
+        .describe('Number of results (1-50, default 20)')
+        .optional(),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .max(9)
+        .default(0)
+        .describe('Pagination offset (max 9, default 0)')
+        .optional(),
+    spellcheck: z
+        .boolean()
+        .default(true)
+        .describe('Whether to spellcheck provided query.')
+        .optional(),
+    safesearch: z
+        .union([z.literal('off'), z.literal('moderate'), z.literal('strict')])
+        .default('moderate')
+        .describe("Filters search results for adult content. The following values are supported: 'off' - No filtering. 'moderate' - Filter out explicit content. 'strict' - Filter out explicit and suggestive content. The default value is 'moderate'.")
+        .optional(),
+    freshness: z
+        .union([z.literal('pd'), z.literal('pw'), z.literal('pm'), z.literal('py'), z.string()])
+        .default('pd')
+        .describe("Filters search results by when they were discovered. The following values are supported: 'pd' - Discovered within the last 24 hours. 'pw' - Discovered within the last 7 Days. 'pm' - Discovered within the last 31 Days. 'py' - Discovered within the last 365 Days. 'YYYY-MM-DDtoYYYY-MM-DD' - Timeframe is also supported by specifying the date range e.g. 2022-04-01to2022-07-30.")
+        .optional(),
+    extra_snippets: z
+        .boolean()
+        .default(false)
+        .describe('A snippet is an excerpt from a page you get as a result of the query, and extra_snippets allow you to get up to 5 additional, alternative excerpts. Only available under Free AI, Base AI, Pro AI, Base Data, Pro Data and Custom plans.')
+        .optional(),
+    goggles: z
+        .array(z.string())
+        .describe("Goggles act as a custom re-ranking on top of Brave's search index. The parameter supports both a url where the Goggle is hosted or the definition of the Goggle. For more details, refer to the Goggles repository (i.e., https://github.com/brave/goggles-quickstart).")
+        .optional(),
+});
+export default params;

package/dist/tools/news/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/summarizer/index.js

@@ -0,0 +1,89 @@
+import { summarizerQueryParams } from './params.js';
+import API from '../../BraveAPI/index.js';
+import { log } from '../../utils.js';
+export const name = 'brave_summarizer';
+export const annotations = {
+    title: 'Brave Summarizer',
+    openWorldHint: true,
+};
+export const description = `
+    Retrieves AI-generated summaries of web search results using Brave's Summarizer API. This tool processes search results to create concise, coherent summaries of information gathered from multiple sources.
+
+    When to use:
+
+    - When you need a concise overview of complex topics from multiple sources
+    - For quick fact-checking or getting key points without reading full articles
+    - When providing users with summarized information that synthesizes various perspectives
+    - For research tasks requiring distilled information from web searches
+
+    Returns a text summary that consolidates information from the search results. Optional features include inline references to source URLs and additional entity information.
+
+    Requirements: Must first perform a web search using brave_web_search with summary=true parameter. Requires a Pro AI subscription to access the summarizer functionality.
+`;
+export const execute = async (params) => {
+    const response = { content: [], isError: false };
+    try {
+        const { summary } = await pollForSummary(params);
+        if (!summary || summary.length === 0) {
+            response.isError = true;
+            response.content.push({
+                type: 'text',
+                text: 'Unable to retrieve a Summarizer summary.',
+            });
+        }
+        else {
+            const summaryText = summary
+                .map((summary_part) => {
+                if (summary_part.type === 'token') {
+                    return summary_part.data;
+                }
+                else if (summary_part.type === 'inline_reference') {
+                    return ` (${summary_part.data?.url})`;
+                }
+                else {
+                    return '';
+                }
+            })
+                .join('');
+            response.content.push({
+                type: 'text',
+                text: summaryText,
+            });
+        }
+    }
+    catch (error) {
+        response.isError = true;
+        response.content.push({
+            type: 'text',
+            text: 'Unable to retrieve a Summarizer summary.',
+        });
+    }
+    return response;
+};
+const pollForSummary = async (params, pollInterval = 50, attempts = 20) => {
+    let result = null;
+    while (!result && attempts > 0) {
+        try {
+            const response = await API.issueRequest('summarizer', params);
+            if (response.status === 'complete') {
+                result = response;
+            }
+        }
+        catch (error) {
+            await log('error', `Error polling for summarizer results: ${error}`);
+            await new Promise((resolve) => setTimeout(resolve, pollInterval));
+        }
+        attempts--;
+    }
+    if (!result) {
+        throw new Error('Summarizer summary could not be retrieved after multiple attempts.');
+    }
+    return result;
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: summarizerQueryParams.shape,
+    execute,
+};

package/dist/tools/summarizer/params.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+export const summarizerQueryParams = z.object({
+    key: z
+        .string()
+        .describe('The key is equal to value of field key as part of the Summarizer response model.'),
+    entity_info: z
+        .boolean()
+        .default(false)
+        .describe('Returns extra entities info with the summary response.')
+        .optional(),
+    inline_references: z
+        .boolean()
+        .default(false)
+        .describe('Adds inline references to the summary response.')
+        .optional(),
+});
+export const chatCompletionsMessage = z.object({
+    role: z
+        .enum(['user'])
+        .default('user')
+        .describe('The role of the message. Only "user" is supported for now.'),
+    content: z
+        .string()
+        .describe('The content of the message. The value is the question to be answered.'),
+});
+export const chatCompletionParams = z.object({
+    messages: z
+        .array(chatCompletionsMessage)
+        .describe('The messages to use for the chat completion. The value is a list of ChatCompletionsMessage response models.'),
+    model: z
+        .enum(['brave-pro', 'brave'])
+        .default('brave-pro')
+        .optional()
+        .describe('The model to use for the chat completion. The value can be "brave-pro" (default) or "brave".'),
+    stream: z
+        .boolean()
+        .default(true)
+        .optional()
+        .describe('Whether to stream the response. The value is `true` by default. When using the OpenAI CLI, use `openai.AsyncOpenAI` for streaming and `openai.OpenAI` for blocking mode.'),
+    country: z
+        .string()
+        .default('us')
+        .optional()
+        .describe('The country backend to use for the chat completion. The value is "us" by default. Note: This parameter is passed in extra_body field when using the OpenAI CLI.'),
+    language: z
+        .string()
+        .default('en')
+        .optional()
+        .describe('The language to use for the chat completion. The value is "en" by default. Note: This parameter is passed in extra_body field when using the OpenAI CLI.'),
+    enable_entities: z
+        .boolean()
+        .default(false)
+        .optional()
+        .describe('Whether to enable entities in the chat completion. The value is `false` by default. Note: This parameter is passed in extra_body field when using the OpenAI CLI.'),
+    enable_citations: z
+        .boolean()
+        .default(false)
+        .optional()
+        .describe('Whether to enable citations in the chat completion. The value is `false` by default. Note: This parameter is passed in extra_body field when using the OpenAI CLI.'),
+});

package/dist/tools/summarizer/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/videos/index.js

@@ -0,0 +1,37 @@
+import params from './params.js';
+import API from '../../BraveAPI/index.js';
+import { stringify } from '../../utils.js';
+export const name = 'brave_video_search';
+export const annotations = {
+    title: 'Brave Video Search',
+    openWorldHint: true,
+};
+export const description = `
+    Searches for videos using Brave's Video Search API and returns structured video results with metadata.
+
+    When to use:
+        - When you need to find videos related to a specific topic, keyword, or query.
+        - Useful for discovering video content, getting video metadata, or finding videos from specific creators/publishers.
+
+    Returns a JSON list of video-related results with title, url, description, duration, and thumbnail_url.
+`;
+export const execute = async (params) => {
+    const response = await API.issueRequest('videos', params);
+    return {
+        content: response.results.map(({ url, title, description, video, thumbnail }) => {
+            const duration = video?.duration;
+            const thumbnail_url = thumbnail?.src;
+            return {
+                type: 'text',
+                text: stringify({ url, title, description, duration, thumbnail_url }),
+            };
+        }),
+    };
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: params.shape,
+    execute,
+};

package/dist/tools/videos/params.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+export const params = z.object({
+    query: z
+        .string()
+        .min(1)
+        .max(400)
+        .refine((str) => str.split(/\s+/).length <= 50, 'Query cannot exceed 50 words')
+        .describe("The user's search query. Query cannot be empty. Limited to 400 characters and 50 words."),
+    country: z
+        .string()
+        .default('US')
+        .describe('Search query country, where the results come from. The country string is limited to 2 character country codes of supported countries.')
+        .optional(),
+    search_lang: z
+        .string()
+        .default('en')
+        .describe('Search language preference. The 2 or more character language code for which the search results are provided.')
+        .optional(),
+    ui_lang: z
+        .string()
+        .default('en-US')
+        .describe('User interface language preferred in response. Usually of the format <language_code>-<country_code>. For more, see RFC 9110.')
+        .optional(),
+    count: z
+        .number()
+        .int()
+        .min(1)
+        .max(50)
+        .default(20)
+        .describe('Number of results (1-50, default 20). Combine this parameter with `offset` to paginate search results.')
+        .optional(),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .max(9)
+        .default(0)
+        .describe('Pagination offset (max 9, default 0). Combine this parameter with `count` to paginate search results.')
+        .optional(),
+    spellcheck: z
+        .boolean()
+        .describe('Whether to spellcheck provided query.')
+        .default(true)
+        .optional(),
+    safesearch: z
+        .union([z.literal('off'), z.literal('moderate'), z.literal('strict')])
+        .default('moderate')
+        .describe("Filters search results for adult content. The following values are supported: 'off' - No filtering. 'moderate' - Filter out explicit content. 'strict' - Filter out explicit and suggestive content. The default value is 'moderate'.")
+        .optional(),
+    freshness: z
+        .union([z.literal('pd'), z.literal('pw'), z.literal('pm'), z.literal('py'), z.string()])
+        .describe("Filters search results by when they were discovered. The following values are supported: 'pd' - Discovered within the last 24 hours. 'pw' - Discovered within the last 7 days. 'pm' - Discovered within the last 31 days. 'py' - Discovered within the last 365 days. 'YYYY-MM-DDtoYYYY-MM-DD' - timeframe is also supported by specifying the date range (e.g. '2022-04-01to2022-07-30').")
+        .optional(),
+});
+export default params;

package/dist/tools/videos/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/web/index.js

@@ -0,0 +1,140 @@
+import params from './params.js';
+import API from '../../BraveAPI/index.js';
+import { stringify } from '../../utils.js';
+export const name = 'brave_web_search';
+export const annotations = {
+    title: 'Brave Web Search',
+    openWorldHint: true,
+};
+export const description = `
+    Performs web searches using the Brave Search API and returns comprehensive search results with rich metadata.
+
+    When to use:
+        - General web searches for information, facts, or current topics
+        - Location-based queries (restaurants, businesses, points of interest)
+        - News searches for recent events or breaking stories
+        - Finding videos, discussions, or FAQ content
+        - Research requiring diverse result types (web pages, images, reviews, etc.)
+
+    Returns a JSON list of web results with title, description, and URL.
+    
+    When the "results_filter" parameter is empty, JSON results may also contain FAQ, Discussions, News, and Video results.
+`;
+export const execute = async (params) => {
+    const response = { content: [], isError: false };
+    const { web, faq, discussions, news, videos, summarizer } = await API.issueRequest('web', params);
+    if (summarizer) {
+        response.content.push({
+            type: 'text',
+            text: `Summarizer key: ${summarizer.key}`,
+        });
+    }
+    if (!web || !Array.isArray(web.results) || web.results.length < 1) {
+        response.isError = true;
+        response.content.push({
+            type: 'text',
+            text: 'No web results found',
+        });
+        return response;
+    }
+    // TODO (Sampson): The following is unnecessarily repetitive.
+    if (web && web.results?.length > 0) {
+        for (const entry of formatWebResults(web)) {
+            response.content.push({
+                type: 'text',
+                text: stringify(entry),
+            });
+        }
+    }
+    if (faq && faq.results?.length > 0) {
+        for (const entry of formatFAQResults(faq)) {
+            response.content.push({
+                type: 'text',
+                text: stringify(entry),
+            });
+        }
+    }
+    if (discussions && discussions.results?.length > 0) {
+        for (const entry of formatDiscussionsResults(discussions)) {
+            response.content.push({
+                type: 'text',
+                text: stringify(entry),
+            });
+        }
+    }
+    if (news && news.results?.length > 0) {
+        for (const entry of formatNewsResults(news)) {
+            response.content.push({
+                type: 'text',
+                text: stringify(entry),
+            });
+        }
+    }
+    if (videos && videos.results?.length > 0) {
+        for (const entry of formatVideoResults(videos)) {
+            response.content.push({
+                type: 'text',
+                text: stringify(entry),
+            });
+        }
+    }
+    return response;
+};
+export const formatWebResults = (web) => {
+    return (web.results || []).map(({ url, title, description, extra_snippets }) => ({
+        url,
+        title,
+        description,
+        extra_snippets,
+    }));
+};
+const formatFAQResults = (faq) => {
+    return (faq.results || []).map(({ question, answer, title, url }) => ({
+        question,
+        answer,
+        title,
+        url,
+    }));
+};
+const formatDiscussionsResults = (discussions) => {
+    return (discussions.results || []).map(({ url, data }) => ({
+        mutated_by_goggles: discussions.mutated_by_goggles,
+        url,
+        data,
+    }));
+};
+const formatNewsResults = (news) => {
+    return (news.results || []).map(({ source, breaking, is_live, age, url, title, description, extra_snippets }) => ({
+        mutated_by_goggles: news.mutated_by_goggles,
+        source,
+        breaking,
+        is_live,
+        age,
+        url,
+        title,
+        description,
+        extra_snippets,
+    }));
+};
+const formatVideoResults = (videos) => {
+    return (videos.results || []).map(({ url, age, title, description, video, thumbnail }) => ({
+        mutated_by_goggles: videos.mutated_by_goggles,
+        url,
+        title,
+        description,
+        age,
+        thumbnail_url: thumbnail?.src,
+        duration: video.duration,
+        view_count: video.views,
+        creator: video.creator,
+        publisher: video.publisher,
+        tags: video.tags,
+    }));
+};
+export default {
+    name,
+    description,
+    annotations,
+    inputSchema: params.shape,
+    execute,
+};