Skip to content
Back to search

brave-search-mcp

An MCP Server implementation that integrates the Brave Search API, providing, Web Search, Local Points of Interest Search, Image Search, Video Search, News Search and LLM Context Search capabilities

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mikechao--brave-search-mcp/badge.svg)](/listings/mikechao--brave-search-mcp)

HTML

<a href="/listings/mikechao--brave-search-mcp"><img src="/api/listings/mikechao--brave-search-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 405 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Brave Search MCP Server
  2. An MCP Server implementation that integrates the [Brave Search API](https://brave.com/search/api/), providing, Web Search, Local Points of Interest Search, Video Search, Image Search, News Search and LLM Context Search capabilities
  3. <a href="https://glama.ai/mcp/servers/@mikechao/brave-search-mcp">
  4. <img width="380" height="200" src="https://glama.ai/mcp/servers/@mikechao/brave-search-mcp/badge" alt="Brave Search MCP server" />
  5. </a>
  6. ## Features
  7. - **Web Search**: Perform a regular search on the web
  8. - **Image Search**: Search the web for images.
  9. - **News Search**: Search the web for news
  10. - **Video Search**: Search the web for videos
  11. - **Local Points of Interest Search**: Search for local physical locations, businesses, restaurants, services, etc
  12. - **LLM Context Search**: Fetch and extract full web page content optimized for reading and synthesizing sources
  13. ## Tools
  14. - **brave_web_search**
  15. - Execute web searches using Brave's API
  16. - Inputs:
  17. - `query` (string): The term to search the internet for
  18. - `count` (number, optional): The number of results to return (max 20, default 10)
  19. - `offset` (number, optional, default 0): The offset for pagination
  20. - `freshness` (enum, optional): Filters search results by when they were discovered
  21. - The following values are supported
  22. - pd: Discovered within the last 24 hours.
  23. - pw: Discovered within the last 7 Days.
  24. - pm: Discovered within the last 31 Days.
  25. - py: Discovered within the last 365 Days
  26. - YYYY-MM-DDtoYYYY-MM-DD: Custom date range (e.g., 2022-04-01to2022-07-30)
  27. - **brave_image_search**
  28. - Get images from the web relevant to the query
  29. - Inputs:
  30. - `query` (string): The term to search the internet for images of
  31. - `count` (number, optional): The number of images to return (max 50, default 10)
  32. - **brave_news_search**
  33. - Searches the web for news
  34. - Inputs:
  35. - `query` (string): The term to search the internet for news articles, trending topics, or recent events
  36. - `count` (number, optional): The number of results to return (max 20, default 10)
  37. - `offset` (number, optional, default 0): The zero-based offset for pagination (max 9)
  38. - `freshness` (enum, optional): Filters search results by when they were discovered
  39. - The following values are supported
  40. - pd: Discovered within the last 24 hours.
  41. - pw: Discovered within the last 7 Days.
  42. - pm: Discovered within the last 31 Days.
  43. - py: Discovered within the last 365 Days
  44. - YYYY-MM-DDtoYYYY-MM-DD: Custom date range (e.g., 2022-04-01to2022-07-30)
  45. - **brave_local_search**
  46. - Search for local businesses, services and points of interest
  47. - Falls back to brave_web_search on the initial page if no location results are found
  48. - Inputs:
  49. - `query` (string): Local search term
  50. - `count` (number, optional): The number of results to return (max 20, default 5)
  51. - `offset` (number, optional, default 0): The zero-based offset for pagination (max 9)
  52. - **brave_video_search**
  53. - Search the web for videos
  54. - Inputs:
  55. - `query`: (string): The term to search for videos
  56. - `count`: (number, optional): The number of videos to return (max 20, default 10)
  57. - `offset` (number, optional, default 0): The zero-based offset for pagination (max 9)
  58. - `freshness` (enum, optional): Filters search results by when they were discovered
  59. - The following values are supported
  60. - pd: Discovered within the last 24 hours.
  61. - pw: Discovered within the last 7 Days.
  62. - pm: Discovered within the last 31 Days.
  63. - py: Discovered within the last 365 Days
  64. - YYYY-MM-DDtoYYYY-MM-DD: Custom date range (e.g., 2022-04-01to2022-07-30)
  65. - **brave_llm_context_search**
  66. - Pre-extracted web content optimized for AI agents, LLM grounding, and RAG pipelines.
  67. - Uses Brave's `balanced` context threshold mode in `compact` mode and disables Brave relevance filtering in `full` mode.
  68. - Inputs:
  69. - `query` (string): The search query. Maximum 400 characters and 50 words.
  70. - `url` (string, optional): Optional URL to target. When provided, query and URL are combined for retrieval and only snippets from this exact URL are returned.
  71. - `count` (number, optional, default 8): The maximum number of search results considered. Minimum 1, maximum 50.
  72. - `maximumNumberOfUrls` (number, optional, default 8): The maximum number of URLs to include in the response. Minimum 1, maximum 50.
  73. - `maximumNumberOfTokens` (number, optional, default 2048): The approximate maximum number of tokens in the returned context. Minimum 1024, maximum 32768.
  74. - `maximumNumberOfSnippets` (number, optional, default 16): The maximum number of snippets across all URLs. Minimum 1, maximum 100.
  75. - `maximumNumberOfTokensPerUrl` (number, optional, default 512): The maximum number of tokens per URL. Minimum 512, maximum 8192.
  76. - `maximumNumberOfSnippetsPerUrl` (number, optional, default 2): The maximum number of snippets per URL. Minimum 1, maximum 100.
  77. - `responseMode` (enum, optional, default `compact`): `compact` applies Brave's `balanced` relevance filtering plus local snippet filtering/truncation. `full` disables Brave's relevance filtering and returns raw snippets without local filtering or truncation.
  78. - `maxSnippetChars` (number, optional, default 400): Maximum characters per snippet in compact mode. Minimum 80, maximum 4000.
  79. - `maxOutputChars` (number, optional, default 8000): Approximate maximum serialized response size in compact mode. Minimum 1000, maximum 100000.
  80. ## OpenAI Apps & MCP Apps Support
  81. <p align="center">
  82. <a href="https://www.youtube.com/watch?v=Z5KiC00gBVE">
  83. <img src="https://img.youtube.com/vi/Z5KiC00gBVE/maxresdefault.jpg" alt="Watch the demo" width="80%">
  84. </a>
  85. <br>
  86. <a href="https://www.youtube.com/watch?v=Z5KiC00gBVE"><em>▶️ Click to watch the demo video</em></a>
  87. </p>
  88. There is now support for [OpenAI Apps](https://developers.openai.com/apps-sdk/) and [MCP Apps](https://modelcontextprotocol.io/docs/extensions/apps) in this MCP Server. When UI mode is enabled for each tool there is a corresponding UI widget that let's you control what gets added to the model's context. See the directions in [usage with ChatGPT section](#usage-with-chatgpt).
  89. ## Configuration
  90. ### Getting an API Key
  91. 1. Sign up for a [Brave Search API account](https://brave.com/search/api/)
  92. 2. Choose a plan
  93. 3. Generate your API key [from the developer dashboard](https://api.search.brave.com/app/keys)
  94. ### Runtime modes
  95. By default the MCP server runs in stdio mode.
  96. ```bash
  97. BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp
  98. ```
  99. To enable Streamable HTTP mode:
  100. ```bash
  101. BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http
  102. ```
  103. By default the server listens on port 3001.
  104. The URL is:
  105. ```
  106. http://0.0.0.0:3001/mcp
  107. ```
  108. There are two configuration modes:
  109. - Env mode: `BRAVE_MCP_CONFIG` is unset. Feature toggles come from environment variables exactly as in previous releases.
  110. - File mode: `BRAVE_MCP_CONFIG=/path/to/config.toml` is set. The TOML file becomes the single source of truth for feature settings, and overlapping feature env vars are ignored with warnings.
  111. ### Environment-only settings
  112. These settings are always read from the process environment, regardless of mode:
  113. - `BRAVE_API_KEY` (required): Brave Search API key.
  114. - `PORT` (optional): HTTP port (default: `3001`).
  115. - `HOST` (optional): Interface to bind to (default: `0.0.0.0`).
  116. - `BRAVE_MCP_CONFIG` (optional): Absolute or relative path to a TOML config file for feature settings.
  117. ### Env mode feature settings
  118. When `BRAVE_MCP_CONFIG` is not set, these feature env vars are supported:
  119. - `ALLOWED_HOSTS` (HTTP mode only): Comma-separated list of allowed hostnames for Host header validation.
  120. - Example: `ALLOWED_HOSTS=localhost,127.0.0.1,my-app.ngrok-free.app`
  121. - Use hostnames only (no scheme/path), e.g. `my-app.ngrok-free.app` not `https://my-app.ngrok-free.app/mcp`
  122. - `BRAVE_MCP_POLICY_FILE`: JSON policy file path.
  123. - `BRAVE_MCP_POLICY_REDACT`: `true` to redact matched text instead of blocking it.
  124. - `BRAVE_MCP_REQUEST_LIMIT`: Positive integer request cap.
  125. - `BRAVE_MCP_WINDOW_SECONDS`: Non-negative integer rolling window size.
  126. - `BRAVE_MCP_COOLDOWN_SECONDS`: Non-negative integer cooldown after the limit is exceeded.
  127. - `BRAVE_MCP_AUDIT_LOG`: `true` to emit audit logs.
  128. - `BRAVE_MCP_AUDIT_LOG_RAW`: `true` to include raw query text in audit logs.
  129. - `BRAVE_MCP_REQUIRE_JUSTIFICATION`: `true` to reject tool calls without a `justification` string.
  130. Examples:
  131. ```bash
  132. # Local only
  133. HOST=127.0.0.1 ALLOWED_HOSTS=localhost,127.0.0.1 BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http
  134. ```
  135. ```bash
  136. # Local with ngrok tunnel
  137. HOST=127.0.0.1 ALLOWED_HOSTS=localhost,127.0.0.1,my-app.ngrok-free.app BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http --ui
  138. ```
  139. ### File mode (`BRAVE_MCP_CONFIG`)
  140. When `BRAVE_MCP_CONFIG` is set, the file controls feature configuration, including the HTTP host allowlist.
  141. ```toml
  142. [auth]
  143. httpApiKey = "sk-..."
  144. requireAuth = true
  145. callerId = "team-a"
  146. [auth.jwt]
  147. jwksUri = "https://idp.example.com/.well-known/jwks.json"
  148. audience = "brave-search-mcp"
  149. clockSkewSeconds = 30
  150. [auth.oauth]
  151. issuer = "https://idp.example.com"
  152. audience = "brave-search-mcp"
  153. clientId = "client-123"
  154. clientSecret = "super-secret"
  155. verifyStrategy = "jwks"
  156. [audit]
  157. enabled = true
  158. logRaw = false
  159. hmacSecret = "audit-secret"
  160. [policy]
  161. file = "/etc/brave-mcp/policy.json"
  162. redact = false
  163. [guardrail]
  164. requestLimit = 100
  165. windowSeconds = 60
  166. cooldownSeconds = 10
  167. requireJustification = false
  168. [server]
  169. allowedHosts = [
  170. "localhost",
  171. "127.0.0.1",
  172. "my-app.ngrok-free.app",
  173. ]
  174. ```
  175. Notes:
  176. - `BRAVE_API_KEY`, `PORT`, and `HOST` remain environment-only even in file mode.
  177. - If you set overlapping feature env vars such as `BRAVE_MCP_REQUEST_LIMIT` or `ALLOWED_HOSTS` alongside `BRAVE_MCP_CONFIG`, startup warns that they are being ignored.
  178. - Unknown TOML keys also emit warnings so typos like `[guardrails]` are visible before you debug runtime behavior.
  179. To validate a config file without starting the server, use the packaged entrypoint after building the app workspace:
  180. ```bash
  181. pnpm -C apps/brave-search-mcp run build
  182. node apps/brave-search-mcp/dist/index.js --check-config ./apps/brave-search-mcp/test/fixtures/config.valid.toml
  183. ```
  184. To run the built local entrypoint in file mode:
  185. ```bash
  186. pnpm -C apps/brave-search-mcp run build
  187. BRAVE_API_KEY="your_key_here" BRAVE_MCP_CONFIG="$PWD/apps/brave-search-mcp/test/fixtures/config.valid.toml" node apps/brave-search-mcp/dist/index.js --http
  188. ```
  189. ### Usage with ChatGPT
  190. The Brave Search MCP Server can be used with the web UI of ChatGPT. It takes a few steps.
  191. #### 1. Enable Developer Mode in ChatGPT
  192. Settings → Apps → Advanced settings → Developer mode
  193. Additional instructions [here](https://platform.openai.com/docs/guides/developer-mode)
  194. #### 2. Run the Brave Search MCP in HTTP mode and UI mode
  195. ```bash
  196. BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http --ui
  197. ```
  198. #### 3. Create a local tunnel to expose the MCP Server to ChatGPT
  199. Sign up and configure [ngrok](https://ngrok.com/), the free plan works.
  200. ```bash
  201. ngrok http 3001
  202. ```
  203. Take note of the forwarding URL.
  204. ```bash
  205. ...
  206. Forwarding https://john-joe-asdf.ngrok-free.dev -> http://localhost:3001
  207. ...
  208. ```
  209. #### 4. Add Brave Search MCP as a Connector to ChatGPT
  210. Open [ChatGPT Apps settings](https://chatgpt.com/#settings/Connectors)
  211. Click Apps
  212. Click Create Apps
  213. Fill out the form using the URL from step 3 as the MCP Server URL, but add `/mcp`.
  214. ```
  215. https://john-joe-asdf.ngrok-free.dev/mcp
  216. ```
  217. For Authentication, select 'No Auth'
  218. Tick the checkbox for 'I understand and want to continue'
  219. Then click Create.
  220. #### 5. Using the Brave Search MCP Server
  221. In the ChatGPT UI, click the '+' button, scroll to '...more', select the newly created Brave Search app, and enter your query.
  222. ### Usage with Claude Code
  223. For [Claude Code](https://claude.ai/code) users, run this command:
  224. **Windows:**
  225. ```bash
  226. claude mcp add-json brave-search '{"command":"cmd","args":["/c","npx","-y","brave-search-mcp"],"env":{"BRAVE_API_KEY":"YOUR_API_KEY_HERE"}}'
  227. ```
  228. **Linux/macOS:**
  229. ```bash
  230. claude mcp add-json brave-search '{"command":"npx","args":["-y","brave-search-mcp"],"env":{"BRAVE_API_KEY":"YOUR_API_KEY_HERE"}}'
  231. ```
  232. Replace `YOUR_API_KEY_HERE` with your actual Brave Search API key.
  233. ### Usage with Claude Desktop
  234. #### MCP Bundle (MCPB)
  235. 1. Download the `mcpb` file from the [Releases](https://github.com/mikechao/brave-search-mcp/releases)
  236. 2. Open it with Claude Desktop
  237. or
  238. Go to File -> Settings -> Extensions and drag the .mcpb file to the window to install it
  239. #### Docker
  240. 1. Clone the repo
  241. 2. Build the image from the repo root
  242. ```bash
  243. docker build -t brave-search-mcp:latest -f apps/brave-search-mcp/Dockerfile .
  244. ```
  245. 3. Run it directly if you want HTTP mode:
  246. ```bash
  247. docker run --rm -p 3001:3001 -e BRAVE_API_KEY="YOUR_API_KEY_HERE" brave-search-mcp:latest --http
  248. ```
  249. 4. Add this to your `claude_desktop_config.json` for stdio mode:
  250. ```json
  251. {
  252. "mcp-servers": {
  253. "brave-search": {
  254. "command": "docker",
  255. "args": [
  256. "run",
  257. "-i",
  258. "--rm",
  259. "-e",
  260. "BRAVE_API_KEY",
  261. "brave-search-mcp"
  262. ],
  263. "env": {
  264. "BRAVE_API_KEY": "YOUR API KEY HERE"
  265. }
  266. }
  267. }
  268. }
  269. ```
  270. #### NPX
  271. Add this to your `claude_desktop_config.json`:
  272. ```json
  273. {
  274. "mcp-servers": {
  275. "brave-search": {
  276. "command": "npx",
  277. "args": [
  278. "-y",
  279. "brave-search-mcp"
  280. ],
  281. "env": {
  282. "BRAVE_API_KEY": "YOUR API KEY HERE"
  283. }
  284. }
  285. }
  286. }
  287. ```
  288. ### Usage with LibreChat
  289. Add this to librechat.yaml
  290. ```yaml
  291. brave-search:
  292. command: sh
  293. args:
  294. - -c
  295. - BRAVE_API_KEY=API KEY npx -y brave-search-mcp
  296. ```
  297. ## Contributing
  298. Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, monorepo structure, and release instructions.
  299. For UI build workflow details, including the entrypoint orchestrator, see [UI Build Orchestrator](CONTRIBUTING.md#ui-build-orchestrator).
  300. ## Disclaimer
  301. This library is not officially associated with Brave Software. It is a third-party implementation of the Brave Search API with a MCP Server.
  302. ## License
  303. This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.