Brave Official

Frequently asked questions

What does the Brave MCP server do?

Brave Search MCP Server An MCP server implementation that integrates the Brave Search API, providing comprehensive search capabilities including web search, local business search, place search, image search, video search, news search, LLM context, 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 . Tools Web Search ( brave web search ) Performs comprehensive web searches with rich result types and advanced filtering options. Parameters: query (string, required): Search terms (max 400 chars, 50 words) country (string, optional): Country code (default: "US") search lang (string, optional): Search language (default: "en") ui lang (string, optional): UI language (default: "en-US") count (number, optional): Results per page (1-20, default: 10) offset (number, optional): Pagination offset (max 9, default: 0) safesearch (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate") freshness (string, optional): Time filter ("pd", "pw", "pm", "py", or date range) text decorations (boolean, optional): Include highlighting markers (default: true) spellcheck (boolean, optional): Enable spell checking (default: true) result filter (array, optional): Filter result types (default: ["web", "query"]) goggles (array, optional): Custom re-ranking definitions units (string, optional): Measurement units ("metric" or "imperial") extra snippets (boolean, optional): Get additional excerpts (Pro plans only) summary (boolean, optional): Enable summary key generation for AI summarization Local Search ( brave local search ) Searches for local businesses and places with detailed information including ratings, hours, and AI-generated descriptions. Parameters: Same as brave web search with automatic location filtering Automatically includes "web" and "locations" in result filter Note: Requires Pro plan for full local search capabilities. Falls back to web search otherwise. Video Search ( brave video search ) Searches for videos with comprehensive metadata and thumbnail information. Parameters: query (string, required): Search terms (max 400 chars, 50 words) country (string, optional): Country code (default: "US") search lang (string, optional): Search language (default: "en") ui lang (string, optional): UI language (default: "en-US") count (number, optional): Results per page (1-50, default: 20) offset (number, optional): Pagination offset (max 9, default: 0) spellcheck (boolean, optional): Enable spell checking (default: true) safesearch (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate") freshness (string, optional): Time filter ("pd", "pw", "pm", "py", or date range) Image Search ( brave image search ) Searches for images with metadata including URLs, dimensions, and confidence scores. Parameters: query (string, required): Search terms (max 400 chars, 50 words) country (string, optional): Country code (default: "US") search lang (string, optional): Search language (default: "en") count (number, optional): Results per page (1-200, default: 50) safesearch (string, optional): Content filtering ("off", "strict", default: "strict") spellcheck (boolean, optional): Enable spell checking (default: true) News Search ( brave news search ) Searches for current news articles with freshness controls and breaking news indicators. Parameters: query (string, required): Search terms (max 400 chars, 50 words) country (string, optional): Country code (default: "US") search lang (string, optional): Search language (default: "en") ui lang (string, optional): UI language (default: "en-US") count (number, optional): Results per page (1-50, default: 20) offset (number, optional): Pagination offset (max 9, default: 0) spellcheck (boolean, optional): Enable spell checking (default: true) safesearch (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate") freshness (string, optional): Time filter (default: "pd" for last 24 hours) extra snippets (boolean, optional): Get additional excerpts (Pro plans only) goggles (array, optional): Custom re-ranking definitions Summarizer Search ( brave summarizer ) Generates AI-powered summaries from web search results using Brave's summarization API. Parameters: key (string, required): Summary key from web search results (use summary: true in web search) entity info (boolean, optional): Include entity information (default: false) inline references (boolean, optional): Add source URL references (default: false) Usage: First perform a web search with summary: true , then use the returned summary key with this tool. Place Search ( brave place search ) Searches for points of interest (POIs) in a specified geographic area using Brave's Place Search API. Returns rich, structured place data including name, address, opening hours, contact info, ratings, photos, categories, and timezone. Parameters: query (string, optional): Query string used to refine the POI search (max 400 chars, 50 words). When omitted, returns general points of interest in the supplied area. latitude (number, optional): Latitude of the search center (-90 to 90). Typically paired with longitude . longitude (number, optional): Longitude of the search center (-180 to 180). Typically paired with latitude . location (string, optional): Location string used as an alternative to latitude / longitude . For US locations prefer the form > > name> (e.g., san francisco ca united states ); for non-US locations use > name> (e.g., tokyo japan ). radius (number, optional): Search radius around the supplied coordinates, in meters. If omitted, the search is performed globally. count (number, optional): Number of results to return (1-50, default 20). country (string, optional): Two-letter country code (default US ). search lang (string, optional): Search language (default en ). ui lang (string, optional): UI language (default en-US ). units (string, optional): Distance units ( metric or imperial , default metric ). safesearch (string, optional): Safe search level ( off , moderate , strict , default strict ). spellcheck (boolean, optional): Whether to spellcheck the query (default true ). geoloc (string, optional): Optional geolocation token used to refine results. Optional request headers: api-version (string, optional): Brave API version ( YYYY-MM-DD ) accept (string, optional): Response media type ( application/json or / ) cache-control (string, optional): Use no-cache to request fresh content user-agent (string, optional): User agent originating the request LLM Context ( brave llm context ) Retrieves pre-extracted web content optimized for AI agents, LLM grounding, and RAG pipelines. Parameters: query (string, required): Search query (max 400 chars, 50 words) country (string, optional): Search country code search lang (string, optional): Search language code count (number, optional): Maximum number of search results considered (1-50) spellcheck (boolean, optional): Enable spell checking maximum number of urls (number, optional): Maximum number of URLs to include (1-50) maximum number of tokens (number, optional): Approximate maximum number of context tokens (1024-32768) maximum number of snippets (number, optional): Maximum number of snippets to include (1-256) context threshold mode (string, optional): Threshold mode ("disabled", "strict", "lenient", "balanced") maximum number of tokens per url (number, optional): Maximum tokens per URL (512-8192) maximum number of snippets per url (number, optional): Maximum snippets per URL (1-100) goggles (string or array, optional): Goggle URL or definition for custom re-ranking freshness (string, optional): Time filter ("pd", "pw", "pm", "py", or date range) enable local (boolean, optional): Enable local recall enable source metadata (boolean, optional): Include source metadata enrichment Optional request headers: x-loc-lat (number, optional): Client latitude (-90 to 90) x-loc-long (number, optional): Client longitude (-180 to 180) x-loc-city (string, optional): Client city name x-loc-state (string, optional): Client state or region code x-loc-state-name (string, optional): Client state or region name x-loc-country (string, optional): Client country code x-loc-postal-code (string, optional): Client postal code api-version (string, optional): Brave API version ( YYYY-MM-DD ) accept (string, optional): Response media type ("application/json" or " / ") cache-control (string, optional): Use no-cache to request fresh content user-agent (string, optional): User agent originating the request Configuration Getting an API Key Sign up for a Brave Search API account Choose a plan: Search : The real-time search data your chatbots & agents need to generate answers. Complete search results (URLs, text, news, images, and more), with additional LLM context optimized for AI. Answers : Summarized, completed answers to any question. Answers grounded on a single search or multiple searches for better accuracy & reduced hallucinations. Generate your API key from the developer dashboard Environment Variables The server supports the following environment variables: BRAVE API KEY : Your Brave Search API key (required unless BRAVE API KEY FILE is set) BRAVE API KEY FILE : Path to a file containing your Brave Search API key. When set, this takes precedence over BRAVE API KEY . Useful for Docker secrets and similar mounted-secret setups. 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: "127.0.0.1"). Binds to loopback only by default; set to "0.0.0.0" to expose the server on all interfaces (required inside containers and on Amazon Bedrock AgentCore). Only do this on a trusted network, since the HTTP endpoint is unauthenticated. BRAVE MCP ALLOWED ORIGINS : Space- or comma-separated list of additional Origin header values permitted for the HTTP transport. Loopback origins are always allowed; browser requests carrying any other Origin are rejected with HTTP 403 to guard against DNS rebinding. Set this when a browser-based client on a real domain needs access. BRAVE MCP ALLOWED HOSTS : Space- or comma-separated list of hostnames permitted in the Host header of the HTTP transport. Matching is on the hostname only and is case-insensitive; a numeric port in an entry (e.g. mcp.example.com:8080 ) is accepted but ignored for matching. Optional, opt-in defense-in-depth: when unset (default) the Host header is not validated, so reverse-proxy and custom-domain deployments are unaffected. When set, only loopback hosts and the listed hostnames are accepted; any other Host (including malformed/non-numeric ports) is rejected with HTTP 403. 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 space-separated whitelist for supported tools BRAVE MCP DISABLED TOOLS : When used, specifies a space-separated blacklist for supported tools BRAVE MCP STATELESS : HTTP stateless mode (default: "true"). When running on Amazon Bedrock Agentcore, set to "true". Command Line Options Installation Usage with Claude Desktop Add this to your claude desktop config.json : Docker NPX Usage with VS Code For quick installation, use the one-click installation buttons below: For manual installation, add the following to your User Settings (JSON) or .vscode/mcp.json : Docker NPX Usage with fx Add this to your /.fx/mcp.json , creating the file if it does not exist: Docker NPX Start fx, or type /mcp reload if it is already running. To verify the connection, type /mcp list . Build Docker Local Build Development Prerequisites Node.js 22.x or higher npm Brave Search API key Setup Clone the repository: Install dependencies: Build the project: Testing via Claude Desktop Add a reference to your local build in claude desktop config.json : Testing via MCP Inspector The Inspector requires Node 22.19 or newer. STDIO — the Inspector launches the server itself, so one terminal is enough: HTTP — the Inspector connects to a URL, so the server must already be listening: serve:http builds, binds 127.0.0.1:8080 , and reads BRAVE API KEY from .env . Available Scripts

How do I install Brave?

Run the install command shown above, then paste the config for your client (Claude Desktop, Claude Code, Cursor, VS Code or Windsurf) into its MCP settings and restart the client.

Is Brave free to use?

The MCP server itself is free to install. The source is public on https://github.com/brave/brave-search-mcp-server. Any third-party service it calls may require its own API key and account.

Which clients support Brave?

Any MCP-compatible client can use it, including Claude Desktop, Claude Code, Cursor, VS Code, Windsurf and custom agents.