# 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

```bash
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`:

```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`:

```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:

```json
{
  "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