Brave Search MCP Server vs Perplexity 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.

Perplexity API Platform MCP Server

The official MCP server implementation for the Perplexity API Platform, providing AI assistants with real-time web search, reasoning, and research capabilities through the Agent API and the Search API.

Remote MCP Server

The remote MCP server is hosted by Perplexity and is the easiest way to get started: same tools, nothing to install or update. The Cursor and VS Code buttons at the top of this page connect to it with one click. If your MCP client does not support remote servers yet, skip to the local server setup below. Connect over Streamable HTTP with your Perplexity API key:

https://api.perplexity.ai/mcp

For Claude Code:

claude mcp add --transport http perplexity https://api.perplexity.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"

See the MCP integration docs for manual Cursor/VS Code configuration, usage from the Anthropic API, and setup for other clients.

Local MCP Server

Get Your API Key

1. Get your Perplexity API Key from the API Portal
2. Replace your_key_here in the configurations below with your API key
3. (Optional) Set timeout: PERPLEXITY_TIMEOUT_MS=600000 (default: 5 minutes)
4. (Optional) Set custom base URL: PERPLEXITY_BASE_URL=https://your-custom-url.com (default: https://api.perplexity.ai)
5. (Optional) Set log level: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (default: ERROR)

Claude Code

claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Or install via plugin:

export PERPLEXITY_API_KEY="your_key_here"
claude
## Then run: /plugin marketplace add perplexityai/modelcontextprotocol
## Then run: /plugin install perplexity

Codex

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Agent Plugins

This repository is packaged as an Agent Plugin, so clients that support the standard can install it directly from this repository. The Agent Plugins format does not carry secrets, so set the PERPLEXITY_API_KEY environment variable through your client's plugin or MCP settings.

Other MCP Clients

Most clients can be configured manually using the same mcpServers wrapper in their client config (as shown for Cursor). If a client has a different schema, check its docs for the exact wrapper format.

For manual setup, these clients all use the same mcpServers structure:

{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

Proxy Setup (For Corporate Networks)

If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:

1. Get your proxy details

• Ask your IT department for your HTTPS proxy address and port.
• You may also need a username and password.

2. Set the proxy environment variable

The easiest and most reliable way for Perplexity MCP is to use PERPLEXITY_PROXY. For example:

export PERPLEXITY_PROXY=https://your-proxy-host:8080

If your proxy needs a username and password, use:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

3. Alternate: Standard environment variables

If you'd rather use the standard variables, we support HTTPS_PROXY and HTTP_PROXY.

[!NOTE]
The server checks proxy settings in this order: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. If none are set, it connects directly to the internet.
URLs must include https://. Typical ports are 8080, 3128, and 80.

Self-Hosted HTTP Mode

For cloud or shared deployments, run the server in HTTP mode.

Environment Variables

Docker

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Node.js

export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http

The server will be accessible at http://localhost:8080/mcp

Available Tools

perplexity_search

Search results include publication and last-updated dates when available. Missing or null dates are omitted from the formatted output.

Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information. Supports recency filters (search_recency_filter), domain restrictions (search_domain_filter), and Fast Search (search_type: "fast") for lower latency and cost.

perplexity_ask

General-purpose conversational AI with real-time web search, backed by the Agent API fast preset. Great for quick questions and everyday searches.

perplexity_research

Deep, comprehensive research backed by the Agent API high preset. Ideal for thorough analysis and detailed reports. Runs can take minutes; the server streams the run and reports progress to clients that request it.

perplexity_reason

Advanced reasoning and problem-solving backed by the Agent API medium preset. Perfect for complex analytical tasks.

perplexity_ask and perplexity_reason accept optional positive-integer max_tokens (total search context, up to 120,000) and max_tokens_per_page (context per result page, up to 20,000). These Agent API budgets control retrieved search content, not generated answer length. When omitted, the preset's search configuration remains in effect.

The legacy search_context_size argument is still accepted, but is translated locally into explicit budgets rather than sent to the Agent API:

This compatibility policy is not an exact equivalent of Sonar's named sizes; the Agent API migration guide has no named-size equivalent. Each explicit budget overrides its corresponding legacy default.

[!NOTE]
Presets are managed configurations (model, search setup, step budget) that Perplexity keeps tuned over time; see the presets guide. Earlier versions of this server called the legacy sonar-pro, sonar-reasoning-pro, and sonar-deep-research models and accepted strip_thinking / reasoning_effort parameters. Those parameters are no longer part of the tool schemas and are ignored if sent; the Agent API produces no <think> tags.

Use as a Library

The package also exports the server factory for embedding in your own Node process:

import { createPerplexityServer } from "@perplexity-ai/mcp-server";

// Single-tenant: reads PERPLEXITY_API_KEY from the environment.
const server = createPerplexityServer("my-service");

// Multi-tenant hosts resolve the key per call instead. When a provider is
// set, the environment variable is never consulted, and a provider that
// returns no key fails the call rather than falling back.
const tenantServer = createPerplexityServer("my-service", {
  apiKey: () => currentRequestApiKey,
});

Mount the returned server on any MCP transport (stdio, streamable HTTP, in-memory).

Troubleshooting

• API Key Issues: Ensure PERPLEXITY_API_KEY is set correctly
• Connection Errors: Check your internet connection and API key validity
• Tool Not Found: Make sure the package is installed and the command path is correct
• Timeout Errors: For very long research queries, set PERPLEXITY_TIMEOUT_MS to a higher value
• Proxy Issues: Verify your PERPLEXITY_PROXY or HTTPS_PROXY setup and ensure api.perplexity.ai isn't blocked by your firewall.
• EOF / Initialize Errors: Some strict MCP clients fail because npx writes installation messages to stdout. Use npx -yq instead of npx -y to suppress this output.

For support, visit community.perplexity.ai or file an issue.