brave_web_search
Search the web using the Brave Search API for general queries, news, and online content. Supports pagination, content filtering, and freshness controls to refine results. Ideal for broad information gathering from diverse sources.
Instructions
Performs a web search using the Brave Search API, ideal for general queries, news, articles, and online content. Use this for broad information gathering, recent events, or when you need diverse web sources. Supports pagination, content filtering, and freshness controls. Maximum 20 results per request, with offset for pagination.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Number of results (1-20, default 10) | |
| offset | No | Pagination offset (max 9, default 0) | |
| query | Yes | Search query (max 400 chars, 50 words) |
Input Schema (JSON Schema)
{
"properties": {
"count": {
"default": 10,
"description": "Number of results (1-20, default 10)",
"type": "number"
},
"offset": {
"default": 0,
"description": "Pagination offset (max 9, default 0)",
"type": "number"
},
"query": {
"description": "Search query (max 400 chars, 50 words)",
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
}
Implementation Reference
- index.ts:331-341 (handler)Handler case for 'brave_web_search' tool: validates input arguments and delegates to performWebSearch function.case "brave_web_search": { if (!isBraveWebSearchArgs(args)) { throw new Error("Invalid arguments for brave_web_search"); } const { query, count = 10 } = args; const results = await performWebSearch(query, count); return { content: [{ type: "text", text: results }], isError: false, }; }
- index.ts:187-218 (helper)Core implementation that performs the Brave Search API web search request, processes results, and formats output.async function performWebSearch(query: string, count: number = 10, offset: number = 0) { checkRateLimit(); const url = new URL('https://api.search.brave.com/res/v1/web/search'); url.searchParams.set('q', query); url.searchParams.set('count', Math.min(count, 20).toString()); // API limit url.searchParams.set('offset', offset.toString()); const response = await fetch(url, { headers: { 'Accept': 'application/json', 'Accept-Encoding': 'gzip', 'X-Subscription-Token': BRAVE_API_KEY } }); if (!response.ok) { throw new Error(`Brave API error: ${response.status} ${response.statusText}\n${await response.text()}`); } const data = await response.json() as BraveWeb; // Extract just web results const results = (data.web?.results || []).map(result => ({ title: result.title || '', description: result.description || '', url: result.url || '' })); return results.map(r => `Title: ${r.title}\nDescription: ${r.description}\nURL: ${r.url}` ).join('\n\n'); }
- index.ts:25-44 (schema)JSON schema defining input parameters for the brave_web_search tool (query required, count/offset optional).inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query (max 400 chars, 50 words)" }, count: { type: "number", description: "Number of results (1-20, default 10)", default: 10 }, offset: { type: "number", description: "Pagination offset (max 9, default 0)", default: 0 }, }, required: ["query"], },
- index.ts:318-320 (registration)Registers brave_web_search (via WEB_SEARCH_TOOL) in the MCP server's listTools response.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [WEB_SEARCH_TOOL, LOCAL_SEARCH_TOOL], }));
- index.ts:169-176 (schema)Type guard function for validating brave_web_search arguments at runtime.function isBraveWebSearchArgs(args: unknown): args is { query: string; count?: number } { return ( typeof args === "object" && args !== null && "query" in args && typeof (args as { query: string }).query === "string" ); }