Verified MCP server: Brave Search
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Brave Search MCP server puts a web search engine behind your AI assistant: web, news, video, image and local results, plus Brave's own AI summaries and a page-content endpoint built for grounding answers. Two packages answer to that name, and picking the wrong one is the most common mistake here. The one we ran, @brave/brave-search-mcp-server, is the official server, published under the @brave npm scope by Brave Software and developed in the brave/brave-search-mcp-server repository. The one most tutorials still show, @modelcontextprotocol/server-brave-search, is the old Anthropic reference implementation: npm marks it deprecated, its source now sits in the archived servers-archived repository, it exposes two tools instead of eight, and it still pulled more downloads last week than the official package. Even Anthropic's own quickstart page still carries a config snippet that installs it. We started the official server, enumerated all 8 tools it exposes, and kept the raw output, including the exact errors it returns when the API key is missing or wrong. [1][3][7][8][9][11][13]
Verification
Method
We spawned the server with npx over stdio, completed the MCP initialize handshake, sent notifications/initialized, and called tools/list. The tool table below is that response, word for word, all 8 of them, and the protocol version above is read straight off the raw initialize reply. This Mac holds no Brave Search API key, and the server refuses to start without one, so BRAVE_API_KEY was set to an obvious placeholder string instead of a real key: enough to get past the startup config check and enumerate what the server offers, not enough to reach Brave. The one tool call we made, brave_web_search, came back with Brave's own SUBSCRIPTION_TOKEN_INVALID, printed below. An authenticated call is pending credentials. The server wrote nothing to stderr on a clean start, so the banner below is the raw initialize reply from stdout.
Startup banner
{"result":{"protocolVersion":"2025-06-18","capabilities":{"logging":{},"tools":{"listChanged":true}},"serverInfo":{"version":"2.1.0","name":"brave-search-mcp-server","title":"Brave Search MCP Server"},"instructions":"Use this server to search the Web for various types of data via the Brave Search API."},"jsonrpc":"2.0","id":1}One real tool call
tools/call brave_web_search {"query": "model context protocol", "count": 3}422
{
"error": {
"code": "SUBSCRIPTION_TOKEN_INVALID",
"detail": "The provided subscription token is invalid.",
"meta": {
"component": "authentication"
},
"status": 422
},
"type": "ErrorResponse"
}Real lines from the captured result: enough to prove the call answered.
Tools
The server answered tools/list with 8 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| brave_web_searchquery*countrysearch_langui_langcountoffsetsafesearchfreshnesstext_decorationsspellcheckresult_filtergogglesunitsextra_snippetssummary | 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. |
| brave_local_searchquery*countrysearch_langui_langcountoffsetsafesearchfreshnesstext_decorationsspellcheckresult_filtergogglesunitsextra_snippetssummary | 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. |
| brave_video_searchquery*countrysearch_langui_langcountoffsetspellchecksafesearchfreshness | 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. |
| brave_image_searchquery*countrysearch_langcountsafesearchspellcheck | 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., ). |
| brave_news_searchquery*countrysearch_langui_langcountoffsetspellchecksafesearchfreshnessextra_snippetsgoggles | 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". |
| brave_summarizerkey*entity_infoinline_references | 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. |
| brave_llm_contextquery*countrysearch_langcountspellcheckmaximum_number_of_urlsmaximum_number_of_tokensmaximum_number_of_snippetscontext_threshold_modemaximum_number_of_tokens_per_urlmaximum_number_of_snippets_per_urlgogglesfreshnessenable_localenable_source_metadatax-loc-latx-loc-longx-loc-cityx-loc-statex-loc-state-namex-loc-countryx-loc-postal-codeapi-versionacceptcache-controluser-agent | Retrieves pre-extracted, relevance-ranked web content using Brave's LLM Context API, optimized for AI agents, LLM grounding, and RAG pipelines. Unlike a traditional web search that returns links and short descriptions, this tool returns the actual substance of matching pages — text chunks, tables, code blocks, and structured data — so the model can reason over it directly. When to use: - Grounding answers in fresh, relevant web content (RAG) - Giving an AI agent ready-to-use page content from a single search call - Question answering and fact-checking against current sources - Gathering source material for research without manually fetching pages - When you need the contents of pages, not just titles, descriptions, and URLs When relaying results in markdown-supporting environments, cite the source URLs from the "sources" map. |
| brave_place_searchqueryradiuscountlatitudelongitudelocationcountrysearch_langui_langunitssafesearchspellcheckgeolocapi-versionacceptcache-controluser-agent | Searches Brave's Place Search API. A single call may populate any combination of 'results' (POIs), 'cities', 'addresses', 'streets', and 'location' (the resolved search area), depending on the query's shape. When to use: - POIs near coordinates or a named area (e.g. "coffee shops in Paris") -> 'results', each with structured business data (postal address, hours, contact, ratings, photos, categories, timezone). - Browsing general POIs (omit 'query'; supply 'latitude'+'longitude' or 'location'). - Disambiguating a bare city name (e.g. "springfield") -> 'cities'. - Resolving a specific address (e.g. "350 5th avenue" with NYC coords) -> 'addresses' (often plus 'streets'). - Looking up a street by name (e.g. "michigan avenue" with Chicago coords) -> 'streets'. Inputs: - Anchor the search via 'latitude'+'longitude' or 'location' (or both). With neither, 'query' is required. - 'addresses' / 'streets' only surface when the query is address-/street-shaped AND geographically anchored. - 'location' format: US -- '<city> <state> <country>' (e.g. 'san francisco ca united states'); non-US -- '<city> <country>' (e.g. 'tokyo japan'). Capitalization and commas don't matter. - 'count' caps results (max 50, default 20). 'radius' (meters) biases toward closer results; it does NOT hard-limit the search area. |
Parameters marked with * are required.
Setup
Copy the block for the app you use. Each one is the configuration this server was verified with.
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": [
"-y",
"@brave/brave-search-mcp-server"
],
"env": {
"BRAVE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Paste your own Brave Search API key, then quit and reopen Claude Desktop. One warning about the README: its Claude Desktop example appends "--transport" and "http" to the args array. That flag turns the process into a web server instead of the stdio program Claude Desktop is waiting to talk to, so leave it out. The block above is the shape we verified. [4][13]
One command in your terminal:
claude mcp add --env BRAVE_API_KEY=YOUR_API_KEY_HERE --transport stdio brave-search -- npx -y @brave/brave-search-mcp-server
Everything after the double dash is the exact command Claude Code will run, and the double dash is required so the server's own flags are not read as Claude Code flags. Add --scope project to write it into a shared .mcp.json instead of your personal config. [14]
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": [
"-y",
"@brave/brave-search-mcp-server"
],
"env": {
"BRAVE_API_KEY": "YOUR_API_KEY_HERE"
}
}
}
}Cursor picks the file up on restart. It also accepts "${env:BRAVE_API_KEY}" as the value, which reads the key from your shell environment instead of writing it into the file. Worth using: a project-level .cursor/mcp.json is plain text that can end up in a repository you push. [15]
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Brave Search Command npx Arguments -y @brave/brave-search-mcp-server Environment Variables BRAVE_API_KEY YOUR_API_KEY_HERE
The Arguments field splits on spaces, so keep it to exactly those three words. The key goes in Environment Variables, never in Arguments. Click Test Connection first: a working server answers with its tool count, eight for this one. [16][4]
No terminal needed
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in a few fields once, and this server's tools are available to your AI in chat and in scheduled routines. The only detour is the Brave Search API key, and it takes about five minutes on Brave's own dashboard.
01
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Go to brave.com/search/api, create an account, and pick a plan. Then open the dashboard at api-dashboard.search.brave.com/app/keys and generate a key. Brave asks for a card even on the entry plans, and both plans include a small monthly credit before charges start, so read the pricing page before you commit.
03
Back in Routines, click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
The form opens in URL (SSE/HTTP) mode. Switch it to Command (stdio): this server is a command, not a web address. Name: Brave Search. Command: npx. Arguments: -y @brave/brave-search-mcp-server, exactly those three words.
05
In Environment Variables add BRAVE_API_KEY with the key you generated. Click Test Connection: Routines starts the server without saving it and reports how many tools it found, eight for this one. If the key is missing entirely, the server exits before it can answer at all. Then click Add Server.
06
The tools work in chat right away. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
Every weekday at 7:30, search the news from the last 24 hours for my three tracked topics, keep only stories from sources I have not already seen this week, and save a five-bullet brief with links as news-brief.md in my Notes folder.
Every Monday at 9:00, search the web for each competitor on my list plus the words pricing, launch and funding, restricted to the last seven days, and write anything new to competitor-watch.md with the date, the source link and one line on why it matters.
On the first of every month at 10:00, search the web and the news for my product name and my own name, list every result published in the last 30 days grouped by site, and save it as mentions.md so I can see who is writing about us.
Troubleshooting
Real errors captured during the verification run, printed exactly as the server returned them.
What you see
Error: A Brave API key is required via --brave-api-key, BRAVE_API_KEY, --brave-api-key-file, or BRAVE_API_KEY_FILE. You can get one at https://brave.com/search/api/. Invalid configuration
The fix
There is no soft failure here. The server validates its configuration before it opens an MCP session at all, and with no key it prints those two lines and quits with exit code 1, so your client reports a server that would not start rather than a tool that would not run. Set BRAVE_API_KEY in the env block (Claude Desktop, Cursor), with --env (Claude Code), or in Environment Variables (Routines). BRAVE_API_KEY_FILE, pointing at a file that holds the key, works too and takes precedence.
What you see
422
{
"error": {
"code": "SUBSCRIPTION_TOKEN_INVALID",
"detail": "The provided subscription token is invalid.",
"meta": {
"component": "authentication"
},
"status": 422
},
"type": "ErrorResponse"
}The fix
This is Brave's answer, not the server's: the key was passed through and the Brave Search API rejected it. This is exactly what our run produced, because we booted the server with a placeholder key on purpose. Check that you copied the key from api-dashboard.search.brave.com/app/keys and not some other token, that the key is still active, and that the plan attached to it is the one you think it is. Several tools, brave_local_search and brave_summarizer among them, say in their own descriptions that they need a Pro plan and will fail on a lower one even with a valid key.
What you see
MCP error -32602: Input validation error: Invalid arguments for tool brave_web_search: [
{
"expected": "string",
"code": "invalid_type",
"path": [
"query"
],
"message": "Invalid input: expected string, received undefined"
}
]The fix
We triggered this by calling brave_web_search with no query. The server validates arguments against its own schema before it calls Brave, so a missing required field or a value of the wrong type never reaches the API. The same shape comes back for a wrong type, for example count sent as the word three instead of a number. If you see it in normal use, the assistant guessed a parameter name: the table above is the full list, and only the fields marked with a star are required.
What you see
Invalid --transport value: 'sse'. Must be one of: stdio, http. Invalid configuration
The fix
There are exactly two transports, stdio and http, and version 2 made stdio the default. Version 1 defaulted to http, which is why older guides pass --transport http or set BRAVE_MCP_TRANSPORT. SSE is not offered. If you do run the HTTP transport, note that it listens without authentication, so keep it bound to 127.0.0.1 and do not widen BRAVE_MCP_HOST to 0.0.0.0 on a shared machine.
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
It is a small program that sits between an AI assistant and the Brave Search API and speaks the Model Context Protocol. Once connected, an assistant such as Claude can run web, news, video, image, local and place searches, ask for an AI summary of a result set, and pull ready-to-read page content for grounding an answer. It runs as a local process on your Mac and talks to your AI app over stdio, which is the default in version 2. [4][3]
The official one, @brave/brave-search-mcp-server, published under the @brave npm scope by Brave Software and developed at github.com/brave/brave-search-mcp-server. The package most guides still show, @modelcontextprotocol/server-brave-search, is the old Anthropic reference implementation: it is flagged deprecated on npm, its code lives in the archived servers-archived repository, and the current modelcontextprotocol/servers README says plainly that it has been replaced by the official server. It still out-downloads the official package, 29,660 to 25,437 in the week ending 2026-08-01, which is a measure of how many stale guides are out there rather than of which one to use. [1][2][7][8][9][11][13]
The running server exposes 8 tools: search (brave_web_search, brave_news_search, brave_video_search, brave_image_search), places (brave_local_search, brave_place_search), and AI-shaped output (brave_summarizer for a written summary, brave_llm_context for extracted page content). The table above is the live tools/list output, word for word. The archived reference package exposes only two of these, brave_web_search and brave_local_search. [10]
Yes, both. You need a Brave Search API account and a key from api-dashboard.search.brave.com/app/keys, set as BRAVE_API_KEY, or as a file path in BRAVE_API_KEY_FILE. Without one the server does not start at all: it prints a configuration error and exits, which we captured in the troubleshooting section above. This is the main practical difference from a zero-credential server like the filesystem one. [4][5][6]
Brave's pricing page lists a Search plan at $5 per 1,000 requests with a 50 queries per second limit, and an Answers plan at $4 per 1,000 requests plus $5 per million tokens with a 2 queries per second limit. Each carries $5 a month in free credits, and Enterprise pricing is custom. Older write-ups quote a free tier of 2,000 queries a month, including the archived package's README, and that plan structure no longer matches what the pricing page says. Figures read on 2026-08-03; check the page before you budget. [12][10]
It is a read-only search client: every tool sends a query to the Brave Search API and returns results, and nothing on your Mac is read or written. Two things are worth watching. The key you paste is a billable credential, so treat the config file that holds it as a secret and prefer the environment-variable form where your client supports it. And if you switch on the HTTP transport, the server itself does not authenticate callers, so leave it bound to the loopback address rather than exposing it on a network. [4]
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor, and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs. VS Code works too, but its file uses a "servers" key and an inputs array rather than the "mcpServers" shape shown here, so do not copy a VS Code snippet into a Claude or Cursor config. [4][14][15][16]
Sources
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
Latest version 2.1.0, published 2026-07-18; 90 versions since 2025-07-16; author Brave Software, Inc.
[2]
[3]
1,344 stars, MIT License, not archived, last push 2026-07-30, per the GitHub API.
[4]
Tool list, BRAVE_API_KEY and BRAVE_API_KEY_FILE, the stdio and http transports, and the Claude Desktop and VS Code config examples.
[5]
getOptions() rejects a missing key and prints the four accepted key sources.
[6]
Exits with process.exit(1) on invalid configuration, before any MCP session opens.
[7]
Latest version 0.6.2, published 2024-12-04, flagged deprecated: Package no longer supported.
[8]
29,660 downloads for the week ending 2026-08-01, more than the official package in the same week.
[9]
Archived repository, 293 stars, last push 2025-05-28, per the GitHub API. Reference MCP servers that are no longer maintained.
[10]
Documents only brave_web_search and brave_local_search, and still advertises a free tier of 2,000 queries a month.
[11]
Lists Brave Search as replaced by the official server and links to brave/brave-search-mcp-server.
[12]
Search plan $5 per 1,000 requests at 50 qps; Answers plan $4 per 1,000 requests plus $5 per million tokens at 2 qps; $5 a month in free credits on each.
[13]
The official Claude Desktop quickstart and the config file location. Its Windows troubleshooting snippet still installs the archived @modelcontextprotocol/server-brave-search.
[14]
The claude mcp add syntax for local stdio servers, the --env and --scope flags, and the required double dash.
[15]
The mcp.json shape, the env block, the ${env:VAR} interpolation form, and the file locations.
[16]
How Routines runs one-click OAuth connectors and any MCP server.
This page describes Brave Search as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. The briefs it writes stay markdown files on your Mac, and there is no cloud bill. Download Routines