Skip to content
Back to search

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,…

Safety scan

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

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/brave/brave-search-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/brave/brave-search-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

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

HTML

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

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

Docker

{
  "mcpServers": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "http"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

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

{
  "inputs": [
    {
      "password": true,
      "id": "brave-api-key",
      "type": "promptString",
      "description": "Brave Search API Key",
    }
  ],
  "servers": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "${input:brave-api-key}"
      }
    }
  }
}

NPX

{
  "inputs": [
    {
      "password": true,
      "id": "brave-api-key",
      "type": "promptString",
      "description": "Brave Search API Key",
    }
  ],
  "servers": {
    "brave-search-mcp-server": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": {
        "BRAVE_API_KEY": "${input:brave-api-key}"
      }
    }
  }
}

Usage with fx

Add this to your `~/.fx/mcp.json`, creating the file if it does not exist:

Docker

{
  "mcp": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

NPX

{
  "mcp": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Start fx, or type `/mcp reload` if it is already running. To verify the connection, type `/mcp list`.

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 · 462 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Brave Search MCP Server
  2. 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.
  3. [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/brave/brave-search-mcp-server)
  4. ## Migration
  5. ### 1.x to 2.x
  6. #### Default transport now STDIO
  7. 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.
  8. #### Response structure of `brave_image_search`
  9. 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).
  10. ## Tools
  11. ### Web Search (`brave_web_search`)
  12. Performs comprehensive web searches with rich result types and advanced filtering options.
  13. **Parameters:**
  14. - `query` (string, required): Search terms (max 400 chars, 50 words)
  15. - `country` (string, optional): Country code (default: "US")
  16. - `search_lang` (string, optional): Search language (default: "en")
  17. - `ui_lang` (string, optional): UI language (default: "en-US")
  18. - `count` (number, optional): Results per page (1-20, default: 10)
  19. - `offset` (number, optional): Pagination offset (max 9, default: 0)
  20. - `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")
  21. - `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)
  22. - `text_decorations` (boolean, optional): Include highlighting markers (default: true)
  23. - `spellcheck` (boolean, optional): Enable spell checking (default: true)
  24. - `result_filter` (array, optional): Filter result types (default: ["web", "query"])
  25. - `goggles` (array, optional): Custom re-ranking definitions
  26. - `units` (string, optional): Measurement units ("metric" or "imperial")
  27. - `extra_snippets` (boolean, optional): Get additional excerpts (Pro plans only)
  28. - `summary` (boolean, optional): Enable summary key generation for AI summarization
  29. ### Local Search (`brave_local_search`)
  30. Searches for local businesses and places with detailed information including ratings, hours, and AI-generated descriptions.
  31. **Parameters:**
  32. - Same as `brave_web_search` with automatic location filtering
  33. - Automatically includes "web" and "locations" in result_filter
  34. **Note:** Requires Pro plan for full local search capabilities. Falls back to web search otherwise.
  35. ### Video Search (`brave_video_search`)
  36. Searches for videos with comprehensive metadata and thumbnail information.
  37. **Parameters:**
  38. - `query` (string, required): Search terms (max 400 chars, 50 words)
  39. - `country` (string, optional): Country code (default: "US")
  40. - `search_lang` (string, optional): Search language (default: "en")
  41. - `ui_lang` (string, optional): UI language (default: "en-US")
  42. - `count` (number, optional): Results per page (1-50, default: 20)
  43. - `offset` (number, optional): Pagination offset (max 9, default: 0)
  44. - `spellcheck` (boolean, optional): Enable spell checking (default: true)
  45. - `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")
  46. - `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)
  47. ### Image Search (`brave_image_search`)
  48. Searches for images with metadata including URLs, dimensions, and confidence scores.
  49. **Parameters:**
  50. - `query` (string, required): Search terms (max 400 chars, 50 words)
  51. - `country` (string, optional): Country code (default: "US")
  52. - `search_lang` (string, optional): Search language (default: "en")
  53. - `count` (number, optional): Results per page (1-200, default: 50)
  54. - `safesearch` (string, optional): Content filtering ("off", "strict", default: "strict")
  55. - `spellcheck` (boolean, optional): Enable spell checking (default: true)
  56. ### News Search (`brave_news_search`)
  57. Searches for current news articles with freshness controls and breaking news indicators.
  58. **Parameters:**
  59. - `query` (string, required): Search terms (max 400 chars, 50 words)
  60. - `country` (string, optional): Country code (default: "US")
  61. - `search_lang` (string, optional): Search language (default: "en")
  62. - `ui_lang` (string, optional): UI language (default: "en-US")
  63. - `count` (number, optional): Results per page (1-50, default: 20)
  64. - `offset` (number, optional): Pagination offset (max 9, default: 0)
  65. - `spellcheck` (boolean, optional): Enable spell checking (default: true)
  66. - `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")
  67. - `freshness` (string, optional): Time filter (default: "pd" for last 24 hours)
  68. - `extra_snippets` (boolean, optional): Get additional excerpts (Pro plans only)
  69. - `goggles` (array, optional): Custom re-ranking definitions
  70. ### Summarizer Search (`brave_summarizer`)
  71. Generates AI-powered summaries from web search results using Brave's summarization API.
  72. **Parameters:**
  73. - `key` (string, required): Summary key from web search results (use `summary: true` in web search)
  74. - `entity_info` (boolean, optional): Include entity information (default: false)
  75. - `inline_references` (boolean, optional): Add source URL references (default: false)
  76. **Usage:** First perform a web search with `summary: true`, then use the returned summary key with this tool.
  77. ### Place Search (`brave_place_search`)
  78. 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.
  79. **Parameters:**
  80. - `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.
  81. - `latitude` (number, optional): Latitude of the search center (-90 to 90). Typically paired with `longitude`.
  82. - `longitude` (number, optional): Longitude of the search center (-180 to 180). Typically paired with `latitude`.
  83. - `location` (string, optional): Location string used as an alternative to `latitude`/`longitude`. For US locations prefer the form `<city> <state> <country name>` (e.g., `san francisco ca united states`); for non-US locations use `<city> <country name>` (e.g., `tokyo japan`).
  84. - `radius` (number, optional): Search radius around the supplied coordinates, in meters. If omitted, the search is performed globally.
  85. - `count` (number, optional): Number of results to return (1-50, default 20).
  86. - `country` (string, optional): Two-letter country code (default `US`).
  87. - `search_lang` (string, optional): Search language (default `en`).
  88. - `ui_lang` (string, optional): UI language (default `en-US`).
  89. - `units` (string, optional): Distance units (`metric` or `imperial`, default `metric`).
  90. - `safesearch` (string, optional): Safe search level (`off`, `moderate`, `strict`, default `strict`).
  91. - `spellcheck` (boolean, optional): Whether to spellcheck the query (default `true`).
  92. - `geoloc` (string, optional): Optional geolocation token used to refine results.
  93. **Optional request headers:**
  94. - `api-version` (string, optional): Brave API version (`YYYY-MM-DD`)
  95. - `accept` (string, optional): Response media type (`application/json` or `*/*`)
  96. - `cache-control` (string, optional): Use `no-cache` to request fresh content
  97. - `user-agent` (string, optional): User agent originating the request
  98. ### LLM Context (`brave_llm_context`)
  99. Retrieves pre-extracted web content optimized for AI agents, LLM grounding, and RAG pipelines.
  100. **Parameters:**
  101. - `query` (string, required): Search query (max 400 chars, 50 words)
  102. - `country` (string, optional): Search country code
  103. - `search_lang` (string, optional): Search language code
  104. - `count` (number, optional): Maximum number of search results considered (1-50)
  105. - `spellcheck` (boolean, optional): Enable spell checking
  106. - `maximum_number_of_urls` (number, optional): Maximum number of URLs to include (1-50)
  107. - `maximum_number_of_tokens` (number, optional): Approximate maximum number of context tokens (1024-32768)
  108. - `maximum_number_of_snippets` (number, optional): Maximum number of snippets to include (1-256)
  109. - `context_threshold_mode` (string, optional): Threshold mode ("disabled", "strict", "lenient", "balanced")
  110. - `maximum_number_of_tokens_per_url` (number, optional): Maximum tokens per URL (512-8192)
  111. - `maximum_number_of_snippets_per_url` (number, optional): Maximum snippets per URL (1-100)
  112. - `goggles` (string or array, optional): Goggle URL or definition for custom re-ranking
  113. - `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)
  114. - `enable_local` (boolean, optional): Enable local recall
  115. - `enable_source_metadata` (boolean, optional): Include source metadata enrichment
  116. **Optional request headers:**
  117. - `x-loc-lat` (number, optional): Client latitude (-90 to 90)
  118. - `x-loc-long` (number, optional): Client longitude (-180 to 180)
  119. - `x-loc-city` (string, optional): Client city name
  120. - `x-loc-state` (string, optional): Client state or region code
  121. - `x-loc-state-name` (string, optional): Client state or region name
  122. - `x-loc-country` (string, optional): Client country code
  123. - `x-loc-postal-code` (string, optional): Client postal code
  124. - `api-version` (string, optional): Brave API version (`YYYY-MM-DD`)
  125. - `accept` (string, optional): Response media type ("application/json" or "*/*")
  126. - `cache-control` (string, optional): Use `no-cache` to request fresh content
  127. - `user-agent` (string, optional): User agent originating the request
  128. ## Configuration
  129. ### Getting an API Key
  130. 1. Sign up for a [Brave Search API account](https://brave.com/search/api/)
  131. 2. Choose a plan:
  132. - **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.
  133. - **Answers**: Summarized, completed answers to any question. Answers grounded on a single search or multiple searches for better accuracy & reduced hallucinations.
  134. 3. Generate your API key from the [developer dashboard](https://api-dashboard.search.brave.com/app/keys)
  135. ### Environment Variables
  136. The server supports the following environment variables:
  137. - `BRAVE_API_KEY`: Your Brave Search API key (required unless `BRAVE_API_KEY_FILE` is set)
  138. - `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.
  139. - `BRAVE_MCP_TRANSPORT`: Transport mode ("http" or "stdio", default: "stdio")
  140. - `BRAVE_MCP_PORT`: HTTP server port (default: 8080)
  141. - `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.
  142. - `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.
  143. - `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.
  144. - `BRAVE_MCP_LOG_LEVEL`: Desired logging level("debug", "info", "notice", "warning", "error", "critical", "alert", or "emergency", default: "info")
  145. - `BRAVE_MCP_ENABLED_TOOLS`: When used, specifies a space-separated whitelist for supported tools
  146. - `BRAVE_MCP_DISABLED_TOOLS`: When used, specifies a space-separated blacklist for supported tools
  147. - `BRAVE_MCP_STATELESS`: HTTP stateless mode (default: "false"). Must be "true" on Amazon Bedrock AgentCore, which sends its own `Mcp-Session-Id` with every request.
  148. ### Command Line Options
  149. ```bash
  150. node dist/index.js [options]
  151. Options:
  152. --brave-api-key <string> Brave API key
  153. --brave-api-key-file <string> Path to file containing Brave API key
  154. --transport <stdio|http> Transport type (default: stdio)
  155. --port <number> HTTP server port (default: 8080)
  156. --host <string> HTTP server host (default: 127.0.0.1)
  157. --allowed-origins <origins...> Allowed Origin header values for HTTP transport (DNS rebinding protection)
  158. --allowed-hosts <hosts...> Allowed Host header values for HTTP transport (opt-in DNS rebinding protection)
  159. --logging-level <string> Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)
  160. --enabled-tools Tools whitelist (only the specified tools will be enabled)
  161. --disabled-tools Tools blacklist (included tools will be disabled)
  162. --stateless <boolean> HTTP Stateless flag
  163. ```
  164. ## Installation
  165. ### Usage with Claude Desktop
  166. Add this to your `claude_desktop_config.json`:
  167. #### Docker
  168. ```json
  169. {
  170. "mcpServers": {
  171. "brave-search": {
  172. "command": "docker",
  173. "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
  174. "env": {
  175. "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
  176. }
  177. }
  178. }
  179. }
  180. ```
  181. #### NPX
  182. ```json
  183. {
  184. "mcpServers": {
  185. "brave-search": {
  186. "command": "npx",
  187. "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
  188. "env": {
  189. "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
  190. }
  191. }
  192. }
  193. }
  194. ```
  195. ### Usage with VS Code
  196. For quick installation, use the one-click installation buttons below:
  197. [![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40brave%2Fbrave-search-mcp-server%22%2C%22--transport%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40brave%2Fbrave-search-mcp-server%22%2C%22--transport%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D&quality=insiders)
  198. [![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22BRAVE_API_KEY%22%2C%22mcp%2Fbrave-search%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=brave-search&inputs=%5B%7B%22password%22%3Atrue%2C%22id%22%3A%22brave-api-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Brave+Search+API+Key%22%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22BRAVE_API_KEY%22%2C%22mcp%2Fbrave-search%22%5D%2C%22env%22%3A%7B%22BRAVE_API_KEY%22%3A%22%24%7Binput%3Abrave-api-key%7D%22%7D%7D&quality=insiders)
  199. For manual installation, add the following to your User Settings (JSON) or `.vscode/mcp.json`:
  200. #### Docker
  201. ```json
  202. {
  203. "inputs": [
  204. {
  205. "password": true,
  206. "id": "brave-api-key",
  207. "type": "promptString",
  208. "description": "Brave Search API Key",
  209. }
  210. ],
  211. "servers": {
  212. "brave-search": {
  213. "command": "docker",
  214. "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"],
  215. "env": {
  216. "BRAVE_API_KEY": "${input:brave-api-key}"
  217. }
  218. }
  219. }
  220. }
  221. ```
  222. #### NPX
  223. ```json
  224. {
  225. "inputs": [
  226. {
  227. "password": true,
  228. "id": "brave-api-key",
  229. "type": "promptString",
  230. "description": "Brave Search API Key",
  231. }
  232. ],
  233. "servers": {
  234. "brave-search-mcp-server": {
  235. "command": "npx",
  236. "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
  237. "env": {
  238. "BRAVE_API_KEY": "${input:brave-api-key}"
  239. }
  240. }
  241. }
  242. }
  243. ```
  244. ### Usage with fx
  245. Add this to your `~/.fx/mcp.json`, creating the file if it does not exist:
  246. #### Docker
  247. ```json
  248. {
  249. "mcp": {
  250. "brave-search": {
  251. "command": "docker",
  252. "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
  253. "env": {
  254. "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
  255. }
  256. }
  257. }
  258. }
  259. ```
  260. #### NPX
  261. ```json
  262. {
  263. "mcp": {
  264. "brave-search": {
  265. "command": "npx",
  266. "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
  267. "env": {
  268. "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
  269. }
  270. }
  271. }
  272. }
  273. ```
  274. Start fx, or type `/mcp reload` if it is already running. To verify the connection, type `/mcp list`.
  275. ## Build
  276. ### Docker
  277. ```bash
  278. docker build -t mcp/brave-search:latest .
  279. ```
  280. ### Local Build
  281. ```bash
  282. npm install
  283. npm run build
  284. ```
  285. ## Development
  286. ### Prerequisites
  287. - Node.js 22.x or higher
  288. - npm
  289. - Brave Search API key
  290. ### Setup
  291. 1. Clone the repository:
  292. ```bash
  293. git clone https://github.com/brave/brave-search-mcp-server.git
  294. cd brave-search-mcp-server
  295. ```
  296. 2. Install dependencies:
  297. ```bash
  298. npm install
  299. ```
  300. 3. Build the project:
  301. ```bash
  302. npm run build
  303. ```
  304. ### Testing via Claude Desktop
  305. Add a reference to your local build in `claude_desktop_config.json`:
  306. ```json
  307. {
  308. "mcpServers": {
  309. "brave-search-dev": {
  310. "command": "node",
  311. "args": ["C:\\GitHub\\brave-search-mcp-server\\dist\\index.js"], // Verify your path
  312. "env": {
  313. "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
  314. }
  315. }
  316. }
  317. }
  318. ```
  319. ### Testing via MCP Inspector
  320. The Inspector requires Node 22.19 or newer.
  321. **STDIO** — the Inspector launches the server itself, so one terminal is enough:
  322. ```bash
  323. npm run build
  324. npx @modelcontextprotocol/inspector node dist/index.js
  325. ```
  326. **HTTP** — the Inspector connects to a URL, so the server must already be listening:
  327. ```bash
  328. # terminal 1
  329. npm run serve:http
  330. # terminal 2
  331. npm run inspector:http
  332. ```
  333. `serve:http` builds, binds `127.0.0.1:8080`, and reads `BRAVE_API_KEY` from `.env`.
  334. ### Available Scripts
  335. - `npm run build`: Build the TypeScript project
  336. - `npm run watch`: Watch for changes and rebuild
  337. - `npm test`: Run the test suite
  338. - `npm run test:docker`: Build the Docker image and test it the way it is deployed: stdio (Docker MCP Catalog, Claude Desktop), HTTP (Docker Hub, compose, ECS), and Amazon Bedrock AgentCore. Requires Docker. To test an existing image instead, run `node --import tsx --test src/docker.e2e.ts` with `BRAVE_MCP_TEST_IMAGE` set.
  339. - `npm run format`: Format code with Prettier
  340. - `npm run format:check`: Check code formatting
  341. - `npm run prepare`: Format and build (runs automatically on npm install)
  342. - `npm run serve:http`: Build, then serve over HTTP at `http://127.0.0.1:8080/mcp`
  343. - `npm run inspector`: Launch an instance of MCP Inspector
  344. - `npm run inspector:http`: Launch MCP Inspector against `http://127.0.0.1:8080/mcp`
  345. ### Docker Compose
  346. For local development with Docker:
  347. ```bash
  348. docker-compose up --build
  349. ```
  350. Set `BRAVE_API_KEY` (or `BRAVE_API_KEY_FILE`) in your shell or a `.env` file before starting the stack. The default `docker-compose.yml` also accepts `BRAVE_API_KEY_FILE` when the path is valid inside the container (for example, from a bind mount or Docker secret).
  351. #### Docker Compose secrets (optional)
  352. To avoid putting the API key in an environment variable, you can use [Docker Compose secrets](https://docs.docker.com/compose/how-tos/use-secrets/). The server reads the key from the path in `BRAVE_API_KEY_FILE`, which must exist inside the container.
  353. 1. Copy the example secret file and add your key:
  354. ```bash
  355. cp secrets/brave_api_key.txt.example secrets/brave_api_key.txt
  356. ```
  357. 2. Start the stack with the optional secrets override:
  358. ```bash
  359. docker compose -f docker-compose.yml -f docker-compose.secrets.example.yml up --build
  360. ```
  361. The override mounts the secret at `/run/secrets/brave_api_key` and sets `BRAVE_API_KEY_FILE` accordingly. See `docker-compose.secrets.example.yml` for the full configuration.
  362. ## License
  363. This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Ratings and comments

Sign in to rate this skill.

Sign in

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