Brave Search MCP Server

A Model Context Protocol (MCP) server that provides web and news search capabilities using the Brave Search API.

Features

• Web Search: Search the web using Brave Search API with comprehensive filtering options
• News Search: Search for recent news articles and breaking stories
• Stdio Transport: Works seamlessly with Claude Desktop and other MCP clients
• TypeScript: Fully typed for better developer experience
• Easy Deployment: Simple npx-based deployment
• Proxy Support: Built-in proxy support for users in China

Installation

Using npx (Recommended)

npx mcp-brave-search

Local Development

# Install dependencies
npm install

# Build the project
npm run build

# Run locally
npm start

Configuration

API Key Setup

1. Get your Brave Search API key from https://api.search.brave.com/
2. Set the environment variable:

export BRAVE_API_KEY="your_api_key_here"

Or create a .env file:

cp .env.example .env
# Edit .env and add your API key

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "mcp-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Proxy Configuration (For Users in China / 代理配置)

If you're in China or behind a firewall, you need to configure a proxy to access the Brave Search API.

如果你在中国大陆，需要配置代理才能访问 Brave Search API。

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "mcp-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_api_key_here",
        "HTTPS_PROXY": "http://127.0.0.1:7890"
      }
    }
  }
}

Supported proxy environment variables:

• HTTPS_PROXY or https_proxy
• HTTP_PROXY or http_proxy

Common proxy ports:

• Clash: 7890
• V2Ray: 10808
• Shadowsocks: 1080

Note: You don't need TUN mode if you configure the HTTPS_PROXY environment variable.

Available Tools

brave_web_search

Search the web using Brave Search API.

Parameters:

• q (required): Search query (max 400 chars, 50 words)
• count (optional): Number of results (1-20, default: 10)
• offset (optional): Pagination offset (0-9, default: 0)
• country (optional): Country code (e.g., "US", "GB", "CN")
• search_lang (optional): Search language (e.g., "en", "zh", "es")
• ui_lang (optional): UI language (e.g., "en-US", "zh-CN")
• safesearch (optional): Filter level - "off", "moderate", "strict"
• freshness (optional): Time filter - "pd" (24h), "pw" (week), "pm" (month), "py" (year)
• text_decorations (optional): Enable text decorations (boolean)
• spellcheck (optional): Enable spellcheck (boolean)

Example:

{
  "q": "TypeScript best practices",
  "count": 5,
  "country": "US",
  "search_lang": "en"
}

brave_news_search

Search for news articles using Brave Search API.

Parameters:

• q (required): Search query (max 400 chars, 50 words)
• count (optional): Number of results (1-20, default: 10)
• offset (optional): Pagination offset (0-9, default: 0)
• country (optional): Country code (e.g., "US", "GB", "CN")
• search_lang (optional): Search language (e.g., "en", "zh", "es")
• ui_lang (optional): UI language (e.g., "en-US", "zh-CN")
• safesearch (optional): Filter level - "off", "moderate", "strict"
• freshness (optional): Time filter - "pd" (24h), "pw" (week), "pm" (month), "py" (year)
• spellcheck (optional): Enable spellcheck (boolean)

Example:

{
  "q": "AI technology news",
  "count": 10,
  "freshness": "pd"
}

Future Enhancements

This server currently implements Web Search and News Search. Future versions may include:

• Image Search
• Video Search
• Local/Places Search
• Suggest API
• HTTP transport mode (currently stdio only)
• Additional search filters and options

API Documentation

For more details about the Brave Search API, visit: https://api-dashboard.search.brave.com/app/documentation/web-search/get-started

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.