@brave/brave-search-mcp-server 1.3.7 → 2.0.3

package/README.md

@@ -1,6 +1,18 @@
 # Brave Search MCP Server
 
-An MCP server implementation that integrates the Brave Search API, providing comprehensive search capabilities including web search, local business search, image search, video search, news search, and AI-powered summarization. This project supports both HTTP and STDIO transports, with HTTP as the default mode.
+An MCP server implementation that integrates the Brave Search API, providing comprehensive search capabilities including web search, local business search, image search, video search, news search, and AI-powered summarization. This project supports both STDIO and HTTP transports, with STDIO as the default mode.
+
+## Migration
+
+### 1.x to 2.x
+
+#### Default transport now STDIO
+
+To follow established MCP conventions, the server now defaults to STDIO. If you would like to continue using HTTP, you will need to set the `BRAVE_MCP_TRANSPORT` environment variable to `http`, or provide the runtime argument `--transport http` when launching the server.
+
+#### Response structure of `brave_image_search`
+
+Version 1.x of the MCP server would return base64-encoded image data along with image URLs. This dramatically slowed down the response, as well as consumed unnecessarily context in the session. Version 2.x removes the base64-encoded data, and returns a response object that more closely reflects the original Brave Search API response. The updated output schema is defined in [`src/tools/images/schemas/output.ts`](https://github.com/brave/brave-search-mcp-server/blob/main/src/tools/images/schemas/output.ts).
 
 ## Tools
 
@@ -99,10 +111,12 @@ Generates AI-powered summaries from web search results using Brave's summarizati
 The server supports the following environment variables:
 
 - `BRAVE_API_KEY`: Your Brave Search API key (required)
-- `BRAVE_MCP_TRANSPORT`: Transport mode ("http" or "stdio", default: "http")
+- `BRAVE_MCP_TRANSPORT`: Transport mode ("http" or "stdio", default: "stdio")
 - `BRAVE_MCP_PORT`: HTTP server port (default: 8080)
 - `BRAVE_MCP_HOST`: HTTP server host (default: "0.0.0.0")
 - `BRAVE_MCP_LOG_LEVEL`: Desired logging level("debug", "info", "notice", "warning", "error", "critical", "alert", or "emergency", default: "info")
+- `BRAVE_MCP_ENABLED_TOOLS`: When used, specifies a whitelist for supported tools
+- `BRAVE_MCP_DISABLED_TOOLS`: When used, specifies a blacklist for supported tools
 
 ### Command Line Options
 
@@ -111,9 +125,12 @@ node dist/index.js [options]
 
 Options:
   --brave-api-key <string>    Brave API key
-  --transport <stdio|http>    Transport type (default: http)
+  --transport <stdio|http>    Transport type (default: stdio)
   --port <number>             HTTP server port (default: 8080)
   --host <string>             HTTP server host (default: 0.0.0.0)
+  --logging-level <string>    Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)
+  --enabled-tools             Tools whitelist (only the specified tools will be enabled)
+  --disabled-tools            Tools blacklist (included tools will be disabled)
 ```
 
 ## Installation
@@ -145,7 +162,7 @@ Add this to your `claude_desktop_config.json`:
   "mcpServers": {
     "brave-search": {
       "command": "npx",
-      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
+      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "http"],
       "env": {
         "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
       }
@@ -283,7 +300,12 @@ node dist/index.js
 npx @modelcontextprotocol/inspector node dist/index.js
 ```
 
-For STDIO mode testing, add `--transport stdio` to the arguments in the Inspector UI.
+STDIO is the default mode. For HTTP mode testing, add `--transport http` to the arguments in the Inspector UI.
+
+### Testing via Smithery.AI
+
+1. Establish and acquire a smithery.ai account and API key
+2. Run `npm run install`, `npm run smithery:build`, and lastly `npm run smithery:dev` to begin testing
 
 ### Available Scripts
 
@@ -293,6 +315,11 @@ For STDIO mode testing, add `--transport stdio` to the arguments in the Inspecto
 - `npm run format:check`: Check code formatting
 - `npm run prepare`: Format and build (runs automatically on npm install)
 
+- `npm run inspector`: Launch an instance of MCP Inspector
+- `npm run inspector:stdio`: Launch a instance of MCP Inspector, configured for STDIO
+- `npm run smithery:build`: Build the project for smithery.ai
+- `npm run smithery:dev`: Launch the development environment for smithery.ai
+
 ### Docker Compose
 
 For local development with Docker:

package/dist/BraveAPI/index.js

@@ -9,10 +9,12 @@ const typeToPathMap = {
     web: '/res/v1/web/search',
     summarizer: '/res/v1/summarizer/search',
 };
-const defaultRequestHeaders = {
-    Accept: 'application/json',
-    'Accept-Encoding': 'gzip',
-    'X-Subscription-Token': config.braveApiKey,
+const getDefaultRequestHeaders = () => {
+    return {
+        Accept: 'application/json',
+        'Accept-Encoding': 'gzip',
+        'X-Subscription-Token': config.braveApiKey,
+    };
 };
 const isValidGoggleURL = (url) => {
     try {
@@ -76,7 +78,7 @@ requestHeaders = {}) {
     }
     // Issue Request
     const urlWithParams = url.toString() + '?' + queryParams.toString();
-    const headers = { ...defaultRequestHeaders, ...requestHeaders };
+    const headers = { ...getDefaultRequestHeaders(), ...requestHeaders };
     const response = await fetch(urlWithParams, { headers });
     // Handle Error
     if (!response.ok) {

package/dist/config.js

@@ -1,25 +1,65 @@
 import { LoggingLevelSchema } from '@modelcontextprotocol/sdk/types.js';
 import { Command } from 'commander';
 import dotenv from 'dotenv';
+import { z } from 'zod';
+import tools from './tools/index.js';
 dotenv.config({ debug: false, quiet: true });
+// Config schema for Smithery.ai
+export const configSchema = z.object({
+    braveApiKey: z.string().describe('Your API key'),
+    enabledTools: z
+        .array(z.string())
+        .describe('Enforces a tool whitelist (cannot be used with disabledTools)')
+        .optional(),
+    disabledTools: z
+        .array(z.string())
+        .describe('Enforces a tool blacklist (cannot be used with enabledTools)')
+        .optional(),
+    loggingLevel: z
+        .enum(LoggingLevelSchema.options)
+        .default('info')
+        .describe('Desired logging level')
+        .optional(),
+});
 const state = {
-    transport: 'http',
+    transport: 'stdio',
     port: 8080,
     host: '0.0.0.0',
     braveApiKey: process.env.BRAVE_API_KEY ?? '',
     loggingLevel: 'info',
     ready: false,
+    enabledTools: [],
+    disabledTools: [],
 };
+export function isToolPermittedByUser(toolName) {
+    return state.enabledTools.length > 0
+        ? state.enabledTools.includes(toolName)
+        : state.disabledTools.includes(toolName) === false;
+}
 export function getOptions() {
     const program = new Command()
         .option('--brave-api-key <string>', 'Brave API key', process.env.BRAVE_API_KEY ?? '')
         .option('--logging-level <string>', 'Logging level', process.env.BRAVE_MCP_LOG_LEVEL ?? 'info')
-        .option('--transport <stdio|http>', 'transport type', process.env.BRAVE_MCP_TRANSPORT ?? 'http')
+        .option('--transport <stdio|http>', 'transport type', process.env.BRAVE_MCP_TRANSPORT ?? 'stdio')
+        .option('--enabled-tools <names...>', 'tools to enable', process.env.BRAVE_MCP_ENABLED_TOOLS?.split(' ') ?? [])
+        .option('--disabled-tools <names...>', 'tools to disable', process.env.BRAVE_MCP_DISABLED_TOOLS?.split(' ') ?? [])
         .option('--port <number>', 'desired port for HTTP transport', process.env.BRAVE_MCP_PORT ?? '8080')
         .option('--host <string>', 'desired host for HTTP transport', process.env.BRAVE_MCP_HOST ?? '0.0.0.0')
         .allowUnknownOption()
         .parse(process.argv);
     const options = program.opts();
+    const toolNames = Object.values(tools).map((tool) => tool.name);
+    // Validate tool inclusion configuration
+    const { enabledTools, disabledTools } = options;
+    if (enabledTools.length > 0 && disabledTools.length > 0) {
+        console.error('Error: --enabled-tools and --disabled-tools cannot be used together');
+        return false;
+    }
+    if ([...enabledTools, ...disabledTools].some((t) => !toolNames.includes(t))) {
+        console.error(`Invalid tool name used. Must be one of: ${toolNames.join(', ')}`);
+        return false;
+    }
+    // Validate all other options
     if (!['stdio', 'http'].includes(options.transport)) {
         console.error(`Invalid --transport value: '${options.transport}'. Must be one of: stdio, http.`);
         return false;
@@ -48,7 +88,12 @@ export function getOptions() {
     state.port = options.port;
     state.host = options.host;
     state.loggingLevel = options.loggingLevel;
+    state.enabledTools = options.enabledTools;
+    state.disabledTools = options.disabledTools;
     state.ready = true;
     return options;
 }
+export function setOptions(options) {
+    return Object.assign(state, options);
+}
 export default state;

package/dist/index.js

@@ -7,13 +7,12 @@ async function main() {
         console.error('Invalid configuration');
         process.exit(1);
     }
-    // stdio requires explicit request
-    if (options.transport === 'stdio') {
-        await stdioServer.start();
+    // default to stdio server unless http is explicitly requested
+    if (options.transport === 'http') {
+        httpServer.start();
         return;
     }
-    // default to http server
-    httpServer.start();
+    await stdioServer.start();
 }
 main().catch((error) => {
     console.error(error);

package/dist/server.js

@@ -1,8 +1,12 @@
 import tools from './tools/index.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import pkg from '../package.json' with { type: 'json' };
-export default function createMcpServer() {
+import { isToolPermittedByUser } from './config.js';
+import { setOptions } from './config.js';
+export { configSchema } from './config.js';
+export default function createMcpServer(options) {
+    if (options?.config)
+        setOptions(options.config);
     const mcpServer = new McpServer({
         version: pkg.version,
         name: 'brave-search-mcp-server',
@@ -14,18 +18,11 @@ export default function createMcpServer() {
         },
         instructions: `Use this server to search the Web for various types of data via the Brave Search API.`,
     });
-    try {
-        mcpServer.server.assertCanSetRequestHandler(SetLevelRequestSchema.shape.method.value);
-        mcpServer.server.setRequestHandler(SetLevelRequestSchema, () => ({}));
-    }
-    catch (error) {
-        /**
-         * An error here signifies native-handling of the SetLevel request.
-         * See https://github.com/modelcontextprotocol/typescript-sdk/issues/871.
-         */
-    }
     for (const tool of Object.values(tools)) {
-        mcpServer.tool(tool.name, tool.description, tool.inputSchema, tool.annotations, tool.execute);
+        // The user may have enabled/disabled this tool at runtime
+        if (!isToolPermittedByUser(tool.name))
+            continue;
+        tool.register(mcpServer);
     }
     return mcpServer;
 }

package/dist/tools/images/index.js

@@ -1,48 +1,61 @@
-import params from './params.js';
+import params from './schemas/input.js';
 import API from '../../BraveAPI/index.js';
-import { stringify } from '../../utils.js';
+import OutputSchema, { SimplifiedImageResultSchema } from './schemas/output.js';
 export const name = 'brave_image_search';
 export const annotations = {
     title: 'Brave Image Search',
     openWorldHint: true,
 };
 export const description = `
-    Performs an image search using the Brave Search API. Helpful for when you need pictures of people, places, or things, ideas for graphic design, inspiration for art, or anything else where images are useful. When relaying the results in a markdown-supporting environment, it is helpful to include some/all of the images in the results. Example: ![Image Description](image_url).
+    Performs an image search using the Brave Search API. Helpful for when you need pictures of people, places, things, graphic design ideas, art inspiration, and more. When relaying results in a markdown environment, it may be helpful to include images in the results (e.g., ![image.title](image.properties.url)).
 `;
 export const execute = async (params) => {
-    const content = [];
     const response = await API.issueRequest('images', params);
-    for (const { url: page_url, title, thumbnail, properties } of response.results) {
-        // Skip results without an image
-        if (!thumbnail?.src)
-            continue;
-        // Prefer property URL as it is the shortest-possible URL
-        const image_url = properties?.url ?? thumbnail.src;
-        const fetched_image = await fetchImage(image_url);
-        if (fetched_image) {
-            const { mimeType, data } = fetched_image;
-            content.push({ type: 'text', text: stringify({ title, page_url, image_url }) }, { type: 'image', mimeType, data });
-        }
-    }
-    return { content, isError: false };
+    const items = response.results.map(simplifySchemaForLLM).filter((o) => o !== null);
+    const structuredContent = OutputSchema.safeParse({
+        type: 'object',
+        items,
+        count: items.length,
+        might_be_offensive: response.extra.might_be_offensive,
+    });
+    const payload = structuredContent.success
+        ? structuredContent.data
+        : structuredContent.error.flatten();
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+        isError: !structuredContent.success,
+        structuredContent: payload,
+    };
 };
-async function fetchImage(url) {
-    try {
-        const response = await fetch(url);
-        const buffer = await response.arrayBuffer();
-        return {
-            data: Buffer.from(buffer).toString('base64'),
-            mimeType: response.headers.get('content-type') ?? 'image/jpeg',
-        };
-    }
-    catch (error) {
-        return null;
-    }
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: name,
+        description: description,
+        inputSchema: params.shape,
+        outputSchema: OutputSchema.shape,
+        annotations: annotations,
+    }, execute);
+};
+function simplifySchemaForLLM(result) {
+    const parsed = SimplifiedImageResultSchema.safeParse({
+        title: result.title,
+        url: result.url,
+        page_fetched: result.page_fetched,
+        confidence: result.confidence,
+        properties: {
+            url: result.properties?.url,
+            width: result.properties?.width,
+            height: result.properties?.height,
+        },
+    });
+    return parsed.success ? parsed.data : null;
 }
 export default {
     name,
     description,
     annotations,
     inputSchema: params.shape,
+    outputSchema: OutputSchema.shape,
     execute,
+    register,
 };

package/dist/tools/images/schemas/output.js

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { ConfidenceSchema, ExtraSchema } from './response.js';
+export const SimplifiedImageResultSchema = z.object({
+    title: z.string(),
+    url: z.string().url(),
+    page_fetched: z.string().datetime(),
+    confidence: ConfidenceSchema,
+    properties: z.object({
+        url: z.string().url(),
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+    }),
+});
+const OutputSchema = z.object({
+    type: z.literal('object'),
+    items: z.array(SimplifiedImageResultSchema),
+    count: z.number().int().nonnegative(),
+    might_be_offensive: ExtraSchema.shape.might_be_offensive,
+});
+export default OutputSchema;

package/dist/tools/images/schemas/response.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+/**
+ * https://api-dashboard.search.brave.com/app/documentation/image-search/responses
+ */
+const QuerySchema = z.object({
+    original: z.string().describe('The original query string.'),
+    altered: z.string().optional().describe('The altered query string.'),
+    spellcheck_off: z.boolean().optional().describe('Whether spellcheck was disabled.'),
+    show_strict_warning: z
+        .boolean()
+        .optional()
+        .describe('When true, some results were blocked by safesearch.'),
+});
+const ThumbnailSchema = z.object({
+    src: z.string().url().optional().describe('The URL of the thumbnail.'),
+    width: z.number().int().positive().optional().describe('The width of the thumbnail.'),
+    height: z.number().int().positive().optional().describe('The height of the thumbnail.'),
+});
+const PropertiesSchema = z.object({
+    url: z.string().url().optional().describe('The URL of the image.'),
+    placeholder: z.string().url().optional().describe('The lower resolution placeholder image.'),
+    width: z.number().int().positive().optional().describe('The width of the image.'),
+    height: z.number().int().positive().optional().describe('The height of the image.'),
+});
+const MetaUrlSchema = z.object({
+    scheme: z.enum(['https', 'http']).optional().describe('The scheme of the URL.'),
+    netloc: z.string().optional().describe('The network location of the URL.'),
+    hostname: z.string().optional().describe('The lowercased hostname of the URL.'),
+    favicon: z.string().url().optional().describe('The URL of the favicon of the URL.'),
+    path: z.string().optional().describe('The path of the URL (useful as a display string).'),
+});
+export const ConfidenceSchema = z
+    .enum(['low', 'medium', 'high'])
+    .describe('The confidence level of the result.');
+const ImageResultSchema = z.object({
+    type: z.literal('image_result').describe('The type of result.'),
+    title: z.string().optional().describe('The title of the image.'),
+    url: z.string().url().optional().describe('The URL of the image.'),
+    source: z.string().url().optional().describe('The source URL of the image.'),
+    page_fetched: z
+        .string()
+        .datetime()
+        .optional()
+        .describe('The date and time the page was fetched.'),
+    thumbnail: ThumbnailSchema.optional().describe('The thumbnail of the image.'),
+    properties: PropertiesSchema.optional().describe('The metadata for the image.'),
+    meta_url: MetaUrlSchema.optional().describe('Information about the URL associated with the image.'),
+    confidence: ConfidenceSchema.optional(),
+});
+export const ExtraSchema = z.object({
+    might_be_offensive: z.boolean().describe('Whether the image might be offensive.'),
+});
+export const ImageSearchApiResponseSchema = z.object({
+    type: z.literal('images').describe('The type of API response.'),
+    query: QuerySchema.describe('The query used to generate the results.'),
+    results: z.array(ImageResultSchema).describe('The results of the image search.'),
+    extra: ExtraSchema.describe('Extra information about the search.'),
+});

package/dist/tools/local/index.js

@@ -53,6 +53,14 @@ export const execute = async (params) => {
         })),
     };
 };
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: name,
+        description: description,
+        inputSchema: webParams.shape,
+        annotations: annotations,
+    }, execute);
+};
 const buildFallbackWebResponse = (web_fallback) => {
     if (!web_fallback || web_fallback.results.length === 0)
         throw new Error('No web results found');
@@ -133,4 +141,5 @@ export default {
     annotations,
     inputSchema: webParams.shape,
     execute,
+    register,
 };

package/dist/tools/news/index.js

@@ -44,10 +44,19 @@ export const execute = async (params) => {
         }),
     };
 };
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: name,
+        description: description,
+        inputSchema: params.shape,
+        annotations: annotations,
+    }, execute);
+};
 export default {
     name,
     description,
     annotations,
     inputSchema: params.shape,
     execute,
+    register,
 };

package/dist/tools/summarizer/index.js

@@ -59,6 +59,14 @@ export const execute = async (params) => {
     }
     return response;
 };
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: name,
+        description: description,
+        inputSchema: summarizerQueryParams.shape,
+        annotations: annotations,
+    }, execute);
+};
 const pollForSummary = async (params, pollInterval = 50, attempts = 20) => {
     let result = null;
     while (!result && attempts > 0) {
@@ -84,4 +92,5 @@ export default {
     annotations,
     inputSchema: summarizerQueryParams.shape,
     execute,
+    register,
 };

package/dist/tools/videos/index.js

@@ -28,10 +28,19 @@ export const execute = async (params) => {
         }),
     };
 };
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: name,
+        description: description,
+        inputSchema: params.shape,
+        annotations: annotations,
+    }, execute);
+};
 export default {
     name,
     description,
     annotations,
     inputSchema: params.shape,
     execute,
+    register,
 };

package/dist/tools/web/index.js

@@ -88,6 +88,14 @@ export const formatWebResults = (web) => {
         extra_snippets,
     }));
 };
+export const register = (mcpServer) => {
+    mcpServer.registerTool(name, {
+        title: name,
+        description: description,
+        inputSchema: params.shape,
+        annotations: annotations,
+    }, execute);
+};
 const formatFAQResults = (faq) => {
     return (faq.results || []).map(({ question, answer, title, url }) => ({
         question,
@@ -137,4 +145,5 @@ export default {
     annotations,
     inputSchema: params.shape,
     execute,
+    register,
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brave/brave-search-mcp-server",
-  "version": "1.3.7",
-  "description": "MCP server for Brave Search. Uses the Brave Search API to return results from the web, including ranked links, images, and videos, as well as AI summaries of pages, rich results, and more.",
+  "version": "2.0.3",
+  "description": "Brave Search MCP Server: web results, images, videos, rich results, AI summaries, and more.",
   "keywords": [
     "api",
     "brave",
@@ -17,6 +17,7 @@
     "url": "https://github.com/brave/brave-search-mcp-server.git"
   },
   "type": "module",
+  "module": "dist/server.js",
   "bin": {
     "brave-search-mcp-server": "dist/index.js"
   },
@@ -25,25 +26,31 @@
   ],
   "scripts": {
     "build": "tsc && shx chmod +x dist/*.js",
+    "smithery:build": "npx @smithery/cli build",
+    "smithery:dev": "npx @smithery/cli dev",
     "prepare": "npm run format && npm run build",
     "watch": "tsc --watch",
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
     "inspector": "npx @modelcontextprotocol/inspector",
-    "inspector:stdio": "npx @modelcontextprotocol/inspector --transport stdio"
+    "inspector:http": "npx @modelcontextprotocol/inspector --transport http"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.17.3",
+    "@modelcontextprotocol/sdk": "1.18.0",
     "commander": "14.0.0",
-    "dotenv": "^17.2.1",
+    "dotenv": "17.2.2",
     "express": "5.1.0",
     "zod": "3.25.76"
   },
   "devDependencies": {
     "@types/express": "5.0.3",
-    "@types/node": "24.3.0",
+    "@types/node": "24.3.1",
     "prettier": "3.6.2",
     "shx": "0.4.0",
+    "tsx": "4.20.5",
     "typescript": "5.9.2"
+  },
+  "overrides": {
+    "formdata-node": "6.0.3"
   }
 }