Brave Search MCP/SSE Server

Overview

• **Centralized Access:** Designed with centrality in mind, allowing organizations or individuals to manage a single Brave Search API key and provide controlled access to multiple internal clients or applications.

• **Observability:** Features robust logging to track requests, API interactions, errors, and rate limits, providing visibility into usage and aiding debugging.

• **Flexible Deployment:** Can be deployed privately within a network or optionally exposed publicly via methods like Kubernetes Ingress or direct Docker port mapping.

Features

• **Web Search**: Access Brave's independent web search index for general queries, news, articles, etc. Supports pagination and filtering controls.

• **Local Search**: Find businesses, restaurants, and services with detailed information like address, phone number, and ratings.

• **Smart Fallbacks**: Local search automatically falls back to a filtered web search if no specific local results are found for the query.

• **Server-Sent Events (SSE)**: Efficient, real-time streaming of search results and tool execution status.

• **Model Context Protocol (MCP)**: Adheres to the MCP standard for seamless integration with compatible clients.

• **Docker Support**: Includes a `Dockerfile` for easy containerization and deployment.

• **Helm Chart**: Provides a Helm chart for straightforward deployment to Kubernetes clusters.

Prerequisites

• **Brave Search API Key**: Required for all deployment methods. See "Getting Started" below.

• **Docker**: Required if deploying using Docker.

• **kubectl & Helm**: Required if deploying to Kubernetes using Helm.

• **Node.js & npm**: Required *only* for local development (Node.js v22.x or later recommended).

• **Git**: Required for cloning the repository for local development or building custom Docker images.

Getting Started

1. Obtain a Brave Search API Key

1. Sign up for a [Brave Search API account](https://brave.com/search/api/).

2. Choose a plan (a free tier is available).

3. Generate your API key from the [developer dashboard](https://api.search.brave.com/app/keys).

2. Configuration

• `PORT`: The port the server listens on (defaults to `8080`).

• `LOG_LEVEL`: Logging verbosity (e.g., `info`, `debug`).

Installation & Usage

Option 1: Docker (Recommended for Deployment)

1. **Obtain a Brave Search API Key:** Follow the steps in the "Getting Started" section.

2. **Pull the Docker image:** Pull the latest image from Docker Hub: ```bash docker pull shoofio/brave-search-mcp-sse:latest ``` Or pull a specific version tag (e.g., `1.0.10`): ```bash docker pull shoofio/brave-search-mcp-sse:1.0.10 ``` *(Alternatively, you can build the image locally if needed. Clone the repository and run `docker build -t brave-search-mcp-sse:custom .`)*

3. **Run the Docker container:** Use the tag you pulled (e.g., `latest` or `1.0.10`): ```bash docker run -d --rm \ -p 8080:8080 \ -e BRAVE_API_KEY="YOUR_API_KEY_HERE" \ -e PORT="8080" # Optional: Define the port if needed # -e LOG_LEVEL="info" # Optional: Set log level --name brave-search-server \ shoofio/brave-search-mcp-sse:latest # Or your specific tag ``` This runs the server in detached mode, mapping port 8080 on your host to the container.

Option 2: Helm (Kubernetes Deployment)

1. **Obtain a Brave Search API Key:** Follow the steps in the "Getting Started" section.

2. **Add the Helm repository:** ```bash helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update ```

3. **Prepare API Key Secret (Recommended):** Create a Kubernetes secret in the target namespace: ```bash kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace> ```

4. **Install the Helm chart:** The chart version corresponds to the application version (latest is `1.0.10`). Install using the secret: ```bash helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.existingSecret=brave-search-secret # Optionally specify a version: --version 1.0.10 ``` Or provide the key directly (less secure): ```bash helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.apiKey="YOUR_API_KEY_HERE" ```

5. **Chart Configuration:** You can customize the deployment by overriding default values. Create a YAML file (e.g., `dev-values.yaml`, `prod-values.yaml`) with your desired settings and use the `-f` flag during installation: `helm install ... -f dev-values.yaml`. Refer to the chart's default [`values.yaml`](./helm/brave-search-mcp-sse/values.yaml) file to see all available configuration options and their default settings.

Option 3: Local Development

1. **Obtain a Brave Search API Key:** Follow the steps in the "Getting Started" section.

2. **Clone the repository:** ```bash git clone <repository_url> # Replace with the actual URL cd brave-search-mcp-sse ```

3. **Install dependencies:** ```bash npm install ```

4. **Set Environment Variables:** Create a `.env` file in the root directory: ```env BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug ```

5. **Build the TypeScript code:** ```bash npm run build ```

6. **Run the server:** ```bash npm start # Or for development with auto-reloading (if nodemon/ts-node-dev is configured) # npm run dev ``` The server will start listening on the configured port (default `8080`).

API / Protocol Interaction

Available Tools

1. **`brave_web_search`** * **Description**: Performs a general web search using the Brave Search API. * **Inputs**: * `query` (string, required): The search query. * `count` (number, optional): Number of results to return (1-20, default 10). * `offset` (number, optional): Pagination offset (0-9, default 0). * *(Other Brave API parameters like `search_lang`, `country`, `freshness`, `result_filter`, `safesearch` might be supported - check `src/services/braveSearchApi.ts`)* * **Output**: Streams MCP messages containing search results (title, URL, snippet, etc.).

2. **`brave_local_search`** * **Description**: Performs a search for local businesses and places using the Brave Search API. Falls back to web search if no local results are found. * **Inputs**: * `query` (string, required): The local search query (e.g., "pizza near me", "cafes in downtown"). * `count` (number, optional): Maximum number of results (1-20, default 5). * **Output**: Streams MCP messages containing local business details (name, address, phone, rating, etc.).

Client Configuration Example (Cursor)

• `transport`: Must be set to `"sse"` for this server.

• `url`: This is the crucial part. * If running locally via Docker (as shown in the example), `http://localhost:8080/sse` is likely correct. * If running in Kubernetes, replace `localhost:8080` with the appropriate Kubernetes Service address/port or the Ingress hostname/path configured to reach the server's port 8080. * Ensure the URL path ends with `/sse`.

Project Structure

Contributing

License