An MCP server implementation that integrates the Brave Search API, providing comprehensive search capabilities including web search, local business search, image search, video search, news search, and AI-powered summarization. This project supports both STDIO and HTTP transports, with STDIO as the default mode. To follow established MCP conventions, the server now defaults to STDIO. If you would l
Add this skill
npx mdskills install brave/brave-search-mcp-serverComprehensive Brave Search integration with six well-documented tools, clear setup instructions, and robust configuration options
1# Brave Search MCP Server23An MCP server implementation that integrates the Brave Search API, providing comprehensive search capabilities including web search, local business search, image search, video search, news search, and AI-powered summarization. This project supports both STDIO and HTTP transports, with STDIO as the default mode.45[](https://deepwiki.com/brave/brave-search-mcp-server)67## Migration89### 1.x to 2.x1011#### Default transport now STDIO1213To 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.1415#### Response structure of `brave_image_search`1617Version 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).1819## Tools2021### Web Search (`brave_web_search`)22Performs comprehensive web searches with rich result types and advanced filtering options.2324**Parameters:**25- `query` (string, required): Search terms (max 400 chars, 50 words)26- `country` (string, optional): Country code (default: "US")27- `search_lang` (string, optional): Search language (default: "en")28- `ui_lang` (string, optional): UI language (default: "en-US")29- `count` (number, optional): Results per page (1-20, default: 10)30- `offset` (number, optional): Pagination offset (max 9, default: 0)31- `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")32- `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)33- `text_decorations` (boolean, optional): Include highlighting markers (default: true)34- `spellcheck` (boolean, optional): Enable spell checking (default: true)35- `result_filter` (array, optional): Filter result types (default: ["web", "query"])36- `goggles` (array, optional): Custom re-ranking definitions37- `units` (string, optional): Measurement units ("metric" or "imperial")38- `extra_snippets` (boolean, optional): Get additional excerpts (Pro plans only)39- `summary` (boolean, optional): Enable summary key generation for AI summarization4041### Local Search (`brave_local_search`)42Searches for local businesses and places with detailed information including ratings, hours, and AI-generated descriptions.4344**Parameters:**45- Same as `brave_web_search` with automatic location filtering46- Automatically includes "web" and "locations" in result_filter4748**Note:** Requires Pro plan for full local search capabilities. Falls back to web search otherwise.4950### Video Search (`brave_video_search`)51Searches for videos with comprehensive metadata and thumbnail information.5253**Parameters:**54- `query` (string, required): Search terms (max 400 chars, 50 words)55- `country` (string, optional): Country code (default: "US")56- `search_lang` (string, optional): Search language (default: "en")57- `ui_lang` (string, optional): UI language (default: "en-US")58- `count` (number, optional): Results per page (1-50, default: 20)59- `offset` (number, optional): Pagination offset (max 9, default: 0)60- `spellcheck` (boolean, optional): Enable spell checking (default: true)61- `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")62- `freshness` (string, optional): Time filter ("pd", "pw", "pm", "py", or date range)6364### Image Search (`brave_image_search`)65Searches for images with automatic fetching and base64 encoding for direct display.6667**Parameters:**68- `query` (string, required): Search terms (max 400 chars, 50 words)69- `country` (string, optional): Country code (default: "US")70- `search_lang` (string, optional): Search language (default: "en")71- `count` (number, optional): Results per page (1-200, default: 50)72- `safesearch` (string, optional): Content filtering ("off", "strict", default: "strict")73- `spellcheck` (boolean, optional): Enable spell checking (default: true)7475### News Search (`brave_news_search`)76Searches for current news articles with freshness controls and breaking news indicators.7778**Parameters:**79- `query` (string, required): Search terms (max 400 chars, 50 words)80- `country` (string, optional): Country code (default: "US")81- `search_lang` (string, optional): Search language (default: "en")82- `ui_lang` (string, optional): UI language (default: "en-US")83- `count` (number, optional): Results per page (1-50, default: 20)84- `offset` (number, optional): Pagination offset (max 9, default: 0)85- `spellcheck` (boolean, optional): Enable spell checking (default: true)86- `safesearch` (string, optional): Content filtering ("off", "moderate", "strict", default: "moderate")87- `freshness` (string, optional): Time filter (default: "pd" for last 24 hours)88- `extra_snippets` (boolean, optional): Get additional excerpts (Pro plans only)89- `goggles` (array, optional): Custom re-ranking definitions9091### Summarizer Search (`brave_summarizer`)92Generates AI-powered summaries from web search results using Brave's summarization API.9394**Parameters:**95- `key` (string, required): Summary key from web search results (use `summary: true` in web search)96- `entity_info` (boolean, optional): Include entity information (default: false)97- `inline_references` (boolean, optional): Add source URL references (default: false)9899**Usage:** First perform a web search with `summary: true`, then use the returned summary key with this tool.100101## Configuration102103### Getting an API Key1041051. Sign up for a [Brave Search API account](https://brave.com/search/api/)1062. Choose a plan:107 - **Free**: 2,000 queries/month, basic web search108 - **Pro**: Enhanced features including local search, AI summaries, extra snippets1093. Generate your API key from the [developer dashboard](https://api-dashboard.search.brave.com/app/keys)110111### Environment Variables112113The server supports the following environment variables:114115- `BRAVE_API_KEY`: Your Brave Search API key (required)116- `BRAVE_MCP_TRANSPORT`: Transport mode ("http" or "stdio", default: "stdio")117- `BRAVE_MCP_PORT`: HTTP server port (default: 8000)118- `BRAVE_MCP_HOST`: HTTP server host (default: "0.0.0.0")119- `BRAVE_MCP_LOG_LEVEL`: Desired logging level("debug", "info", "notice", "warning", "error", "critical", "alert", or "emergency", default: "info")120- `BRAVE_MCP_ENABLED_TOOLS`: When used, specifies a whitelist for supported tools121- `BRAVE_MCP_DISABLED_TOOLS`: When used, specifies a blacklist for supported tools122- `BRAVE_MCP_STATELESS`: HTTP stateless mode (default: "true"). When running on Amazon Bedrock Agentcore, set to "true".123124### Command Line Options125126```bash127node dist/index.js [options]128129Options:130 --brave-api-key <string> Brave API key131 --transport <stdio|http> Transport type (default: stdio)132 --port <number> HTTP server port (default: 8080)133 --host <string> HTTP server host (default: 0.0.0.0)134 --logging-level <string> Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)135 --enabled-tools Tools whitelist (only the specified tools will be enabled)136 --disabled-tools Tools blacklist (included tools will be disabled)137 --stateless <boolean> HTTP Stateless flag138```139140## Installation141142### Installing via Smithery143144To install Brave Search automatically via [Smithery](https://smithery.ai/server/brave):145146```bash147npx -y @smithery/cli install brave148```149150### Usage with Claude Desktop151152Add this to your `claude_desktop_config.json`:153154#### Docker155156```json157{158 "mcpServers": {159 "brave-search": {160 "command": "docker",161 "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],162 "env": {163 "BRAVE_API_KEY": "YOUR_API_KEY_HERE"164 }165 }166 }167}168```169170#### NPX171172```json173{174 "mcpServers": {175 "brave-search": {176 "command": "npx",177 "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "http"],178 "env": {179 "BRAVE_API_KEY": "YOUR_API_KEY_HERE"180 }181 }182 }183}184```185186### Usage with VS Code187188For quick installation, use the one-click installation buttons below:189190[](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) [](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)191[](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) [](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)192193For manual installation, add the following to your User Settings (JSON) or `.vscode/mcp.json`:194195#### Docker196197```json198{199 "inputs": [200 {201 "password": true,202 "id": "brave-api-key",203 "type": "promptString",204 "description": "Brave Search API Key",205 }206 ],207 "servers": {208 "brave-search": {209 "command": "docker",210 "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"],211 "env": {212 "BRAVE_API_KEY": "${input:brave-api-key}"213 }214 }215 }216}217```218219#### NPX220221```json222{223 "inputs": [224 {225 "password": true,226 "id": "brave-api-key",227 "type": "promptString",228 "description": "Brave Search API Key",229 }230 ],231 "servers": {232 "brave-search-mcp-server": {233 "command": "npx",234 "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],235 "env": {236 "BRAVE_API_KEY": "${input:brave-api-key}"237 }238 }239 }240}241```242243## Build244245### Docker246247```bash248docker build -t mcp/brave-search:latest .249```250251### Local Build252253```bash254npm install255npm run build256```257258## Development259260### Prerequisites261262- Node.js 22.x or higher263- npm264- Brave Search API key265266### Setup2672681. Clone the repository:269```bash270git clone https://github.com/brave/brave-search-mcp-server.git271cd brave-search-mcp-server272```2732742. Install dependencies:275```bash276npm install277```2782793. Build the project:280```bash281npm run build282```283284### Testing via Claude Desktop285286Add a reference to your local build in `claude_desktop_config.json`:287288```json289{290 "mcpServers": {291 "brave-search-dev": {292 "command": "node",293 "args": ["C:\\GitHub\\brave-search-mcp-server\\dist\\index.js"], // Verify your path294 "env": {295 "BRAVE_API_KEY": "YOUR_API_KEY_HERE"296 }297 }298 }299}300```301302### Testing via MCP Inspector3033041. Build and start the server:305```bash306npm run build307node dist/index.js308```3093102. In another terminal, start the MCP Inspector:311```bash312npx @modelcontextprotocol/inspector node dist/index.js313```314315STDIO is the default mode. For HTTP mode testing, add `--transport http` to the arguments in the Inspector UI.316317### Testing via Smithery.AI3183191. Establish and acquire a smithery.ai account and API key3202. Run `npm run install`, `npm run smithery:build`, and lastly `npm run smithery:dev` to begin testing321322### Available Scripts323324- `npm run build`: Build the TypeScript project325- `npm run watch`: Watch for changes and rebuild326- `npm run format`: Format code with Prettier327- `npm run format:check`: Check code formatting328- `npm run prepare`: Format and build (runs automatically on npm install)329330- `npm run inspector`: Launch an instance of MCP Inspector331- `npm run inspector:stdio`: Launch a instance of MCP Inspector, configured for STDIO332- `npm run smithery:build`: Build the project for smithery.ai333- `npm run smithery:dev`: Launch the development environment for smithery.ai334335### Docker Compose336337For local development with Docker:338339```bash340docker-compose up --build341```342343## License344345This 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.346
Full transparency — inspect the skill content before installing.