Brave Search MCP Server

An MCP (Model Context Protocol) server that provides web search via Brave Search API. Designed for Claude Code and Claude Desktop integration.

Features:

• Web search with freshness filters (past day/week/month/year)
• Full page content fetching with markdown extraction
• AI-optimized result metadata (authority, content type, recency)
• Usage tracking with monthly limits (2,000 free requests)

Prerequisites

• Node.js 18+
• Brave Search API key (free tier)

Getting a Brave API Key

1. Go to https://brave.com/search/api/
2. Click "Get Started" or "Get API Key"
3. Create an account or sign in
4. Navigate to API keys section
5. Generate a new API key
6. Copy the key (you won't see it again)

Note: Free tier includes 2,000 requests/month with no rate limiting.

Installation

git clone <repo-url>
cd bravesearchmcp
npm install
cp .env.example .env
# Edit .env and add your BRAVE_API_KEY

Claude Desktop Configuration

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/bravesearchmcp/src/index.ts"],
      "env": {
        "BRAVE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["tsx", "C:\\path\\to\\bravesearchmcp\\src\\index.ts"],
      "env": {
        "BRAVE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code Configuration

Add to your Claude Code MCP settings:

{
  "brave-search": {
    "command": "npx",
    "args": ["tsx", "/path/to/bravesearchmcp/src/index.ts"],
    "env": {
      "BRAVE_API_KEY": "your_api_key_here"
    }
  }
}

Available Tools

Tool	Description
brave_web_search	Search the web with optional freshness filter and result count
brave_fetch_page	Fetch and extract content from a URL as markdown

Usage Examples

Search:

Use brave_web_search to find recent articles about TypeScript 5.4 features

Fetch page:

Use brave_fetch_page to get the content from https://example.com/article

Usage Tracking

The server tracks your monthly API usage:

• Displayed with each search result: "Usage: X/2000 (Y%)"
• Warning at 80%: "Warning: approaching limit"
• Warning at 95%: "Critical: nearly exhausted"
• Counter resets on the 1st of each month
• Usage stored in .brave-usage.json (gitignored)

Troubleshooting

Issue	Solution
"BRAVE_API_KEY environment variable is required"	Set the API key in Claude Desktop config or .env file
"Invalid API key"	Check your key at brave.com/search/api dashboard
"Rate limit exceeded"	Wait a moment - Brave has burst protection
Server not appearing in Claude	Restart Claude Desktop after config changes

License

MIT