mcp-brave-search/README.md

Brave Search MCP Server - Web and News Search via stdio

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

```bash
npx mcp-brave-search
```

### Local Development

```bash
# 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/](https://api.search.brave.com/)
2. Set the environment variable:

```bash
export BRAVE_API_KEY="your_api_key_here"
```

Or create a `.env` file:

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

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

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