Brave Search MCP Server vs Tavily MCP Server

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 <city> <state> <country name> (e.g., san francisco ca united states); for non-US locations use <city> <country 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

1. Sign up for a Brave Search API account
2. 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.
3. 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: "false"). Must be "true" on Amazon Bedrock AgentCore, which sends its own Mcp-Session-Id with every request.

Command Line Options

node dist/index.js [options]

Options:
  --brave-api-key <string>        Brave API key
  --brave-api-key-file <string>   Path to file containing Brave API key
  --transport <stdio|http>    Transport type (default: stdio)
  --port <number>             HTTP server port (default: 8080)
  --host <string>             HTTP server host (default: 127.0.0.1)
  --allowed-origins <origins...>  Allowed Origin header values for HTTP transport (DNS rebinding protection)
  --allowed-hosts <hosts...>  Allowed Host header values for HTTP transport (opt-in DNS rebinding protection)
  --logging-level <string>    Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)
  --enabled-tools             Tools whitelist (only the specified tools will be enabled)
  --disabled-tools            Tools blacklist (included tools will be disabled)
  --stateless  <boolean>      HTTP Stateless flag

Installation

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.

Build

Docker

docker build -t mcp/brave-search:latest .

Local Build

npm install
npm run build

Development

Prerequisites

• Node.js 22.x or higher
• npm
• Brave Search API key

Setup

1. Clone the repository:

git clone https://github.com/brave/brave-search-mcp-server.git
cd brave-search-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Testing via Claude Desktop

Add a reference to your local build in claude_desktop_config.json:

{
  "mcpServers": {
    "brave-search-dev": {
      "command": "node",
      "args": ["C:\\GitHub\\brave-search-mcp-server\\dist\\index.js"], // Verify your path
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Testing via MCP Inspector

The Inspector requires Node 22.19 or newer.

STDIO — the Inspector launches the server itself, so one terminal is enough:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

HTTP — the Inspector connects to a URL, so the server must already be listening:

## terminal 1
npm run serve:http

## terminal 2
npm run inspector:http

serve:http builds, binds 127.0.0.1:8080, and reads BRAVE_API_KEY from .env.

Available Scripts

• npm run build: Build the TypeScript project

• npm run watch: Watch for changes and rebuild

• npm test: Run the test suite

• 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.

• npm run format: Format code with Prettier

• npm run format:check: Check code formatting

• npm run prepare: Format and build (runs automatically on npm install)

• npm run serve:http: Build, then serve over HTTP at http://127.0.0.1:8080/mcp

• npm run inspector: Launch an instance of MCP Inspector

• npm run inspector:http: Launch MCP Inspector against http://127.0.0.1:8080/mcp

Docker Compose

For local development with Docker:

docker-compose up --build

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).

Docker Compose secrets (optional)

To avoid putting the API key in an environment variable, you can use Docker Compose secrets. The server reads the key from the path in BRAVE_API_KEY_FILE, which must exist inside the container.

1. Copy the example secret file and add your key:

cp secrets/brave_api_key.txt.example secrets/brave_api_key.txt

2. Start the stack with the optional secrets override:

docker compose -f docker-compose.yml -f docker-compose.secrets.example.yml up --build

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.

License

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.

Tavily MCP Server

The Tavily MCP server provides:

• search, extract, map, crawl tools
• Real-time web search capabilities through the tavily-search tool
• Intelligent data extraction from web pages via the tavily-extract tool
• Powerful web mapping tool that creates a structured map of website
• Web crawler that systematically explores websites

📚 Helpful Resources

• Tutorial on combining Tavily MCP with Neo4j MCP server
• Tutorial on integrating Tavily MCP with Cline in VS Code

Remote MCP Server

Connect directly to Tavily's remote MCP server instead of running it locally. This provides a seamless experience without requiring local installation or configuration.

Simply use the remote MCP server URL with your Tavily API key:

https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Get your Tavily API key from tavily.com.

Alternatively, you can pass your API key through an Authorization header if the MCP client supports this:

Authorization: Bearer <your-api-key>

Note: When using the remote MCP, you can specify default parameters for all requests by including a DEFAULT_PARAMETERS header containing a JSON object with your desired defaults. Example:

{"include_images":true, "search_depth": "basic", "max_results": 10}

Connect to Claude Code

Claude Code is Anthropic's official CLI tool for Claude. You can add the Tavily MCP server using the claude mcp add command. There are two ways to authenticate:

Option 1: API Key in URL

Pass your API key directly in the URL. Replace <your-api-key> with your actual Tavily API key:

claude mcp add --transport http tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Option 2: OAuth Authentication Flow

Add the server without an API key in the URL:

claude mcp add --transport http tavily https://mcp.tavily.com/mcp

After adding, you'll need to complete the authentication flow:

1. Run claude to start Claude Code
2. Type /mcp to open the MCP server management
3. Select the Tavily server and complete the authentication process

Tip: Add --scope user to either command to make the Tavily MCP server available globally across all your projects:

claude mcp add --transport http --scope user tavily https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

Once configured, you'll have access to the Tavily search, extract, map, and crawl tools.

Connect to Cursor

Click the ⬆️ Add to Cursor ⬆️ button, this will do most of the work for you but you will still need to edit the configuration to add your API-KEY. You can get a Tavily API key here.

once you click the button you should be redirect to Cursor ...

Step 1

Click the install button

Step 2

You should see the MCP is now installed, if the blue slide is not already turned on, manually turn it on. You also need to edit the configuration to include your own Tavily API key.

Step 3

You will then be redirected to your mcp.json file where you have to add your-api-key.

{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
      "env": {}
    }
  }
}

Remote MCP Server OAuth Flow

The Tavily Remote MCP server supports secure OAuth authentication, allowing you to connect and authorize seamlessly with compatible clients.

How to Set Up OAuth Authentication

A. Using MCP Inspector:

• Open the MCP Inspector and click "Open Auth Settings".
• Select the OAuth flow and complete these steps:
  1. Metadata discovery
  2. Client registration
  3. Preparing authorization
  4. Request authorization and obtain the authorization code
  5. Token request
  6. Authentication complete

Once finished, you will receive an access token that lets you securely make authenticated requests to the Tavily Remote MCP server.

B. Using other MCP Clients (Example: Cursor):

You can configure your MCP client to use OAuth without including your Tavily API key in the URL. For example, in your mcp.json:

{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx mcp-remote https://mcp.tavily.com/mcp",
      "env": {}
    }
  }
}

If you need to clear stored OAuth credentials and reauthenticate, run:

rm -rf ~/.mcp-auth

Note:

• OAuth authentication is optional. You can still use API key authentication at any time by including your Tavily API key in the URL query parameter (?tavilyApiKey=...) or by setting it in the Authorization header, as described above.

Choosing an Account for OAuth

Each time you connect, Tavily asks whether to use your personal account or one of your organizations. To switch Tavily logins, choose Use a different account.

• Key used: the account's mcp_auth_default key. Tavily creates it if it doesn't exist.
• Organization keys: used even if another member created the key or your organization restricts key access.
• Personal accounts off: if an organization you belong to disables personal accounts, Personal isn't offered.
• Lost access: if you lose access to the account or its key is deleted, requests fail and ask you to reconnect. Tavily never switches accounts on its own.

Local MCP

Prerequisites 🔧

Before you begin, ensure you have:

• Tavily API key
  • If you don't have a Tavily API key, you can sign up for a free account here
• Claude Desktop or Cursor
• Node.js (v20 or higher)
  • You can verify your Node.js installation by running:
    • node --version
• Git installed (only needed if using Git installation method)
  • On macOS: brew install git
  • On Linux:
    • Debian/Ubuntu: sudo apt install git
    • RedHat/CentOS: sudo yum install git
  • On Windows: Download Git for Windows

Running with NPX

npx -y tavily-mcp@latest

Default Parameters Configuration ⚙️

You can set default parameter values for the tavily-search tool using the DEFAULT_PARAMETERS environment variable. This allows you to configure default search behavior without specifying these parameters in every request.

Example Configuration

export DEFAULT_PARAMETERS='{"include_images": true}'

Example usage from Client

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here",
        "DEFAULT_PARAMETERS": "{\"include_images\": true, \"max_results\": 15, \"search_depth\": \"advanced\"}"
      }
    }
  }
}

Identifying the End User (Optional)

You can optionally identify the end user on whose behalf requests are being made by setting the TAVILY_HUMAN_ID environment variable. When set, Tavily MCP forwards it as the X-Human-Id header on every API call, enabling per-user analytics.

This is entirely optional — leave it unset and behavior is unchanged.

{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@latest"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here",
        "TAVILY_HUMAN_ID": "your-user-id"
      }
    }
  }
}

Privacy note: Tavily hashes human_id server-side (SHA-256) before storage, so the raw value is never persisted. Even so, prefer opaque identifiers (e.g. an internal user ID) over raw PII like emails when possible.

Acknowledgments ✨

• Model Context Protocol for the MCP specification
• Anthropic for Claude Desktop