Brave Search MCP/SSE Server
An implementation of the Model Context Protocol (MCP) using Server-Sent Events (SSE) that integrates the Brave Search API, providing AI models and other clients with web and local search capabilities through a streaming interface.
Overview
This server acts as a tool provider for Large Language Models that understand the Model Context Protocol. It exposes Brave's powerful web and local search functionalities via an SSE connection, allowing for real-time streaming of search results and status updates.
Key Design Goals:
- 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
Dockerfilefor easy containerization and deployment. - Helm Chart: Provides a Helm chart for straightforward deployment to Kubernetes clusters.
Prerequisites
Depending on your chosen deployment method, you will need some of the following:
- 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
- Sign up for a Brave Search API account.
- Choose a plan (a free tier is available).
- Generate your API key from the developer dashboard.
2. Configuration
The server requires the Brave Search API key to be set via the BRAVE_API_KEY environment variable.
Other potential environment variables (check src/config/config.ts for details):
PORT: The port the server listens on (defaults to8080).LOG_LEVEL: Logging verbosity (e.g.,info,debug).
Set these variables in your environment or using a .env file in the project root for local development.
Installation & Usage
Choose the deployment method that best suits your needs:
Option 1: Docker (Recommended for Deployment)
Prerequisites: Docker installed.
- Obtain a Brave Search API Key: Follow the steps in the "Getting Started" section.
- Pull the Docker image:
Pull the latest image from Docker Hub:
Or pull a specific version tag (e.g.,docker pull shoofio/brave-search-mcp-sse:latest1.0.10):
(Alternatively, you can build the image locally if needed. Clone the repository and rundocker pull shoofio/brave-search-mcp-sse:1.0.10docker build -t brave-search-mcp-sse:custom .) - Run the Docker container:
Use the tag you pulled (e.g.,
latestor1.0.10):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
Option 2: Helm (Kubernetes Deployment)
Prerequisites: kubectl connected to your cluster, Helm installed.
-
Obtain a Brave Search API Key: Follow the steps in the "Getting Started" section.
-
Add the Helm repository:
helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update -
Prepare API Key Secret (Recommended): Create a Kubernetes secret in the target namespace:
kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace> -
Install the Helm chart: The chart version corresponds to the application version (latest is
1.0.10). Install using the secret: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.10Or provide the key directly (less secure):
helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.apiKey="YOUR_API_KEY_HERE" -
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-fflag during installation:helm install ... -f dev-values.yaml.Refer to the chart's default
values.yamlfile to see all available configuration options and their default settings.
Option 3: Local Development
Prerequisites: Node.js and npm (v22.x or later recommended), Git.
- Obtain a Brave Search API Key: Follow the steps in the "Getting Started" section.
- Clone the repository:
git clone <repository_url> # Replace with the actual URL cd brave-search-mcp-sse - Install dependencies:
npm install - Set Environment Variables:
Create a
.envfile in the root directory:BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug - Build the TypeScript code:
npm run build - Run the server:
npm start # Or for development with auto-reloading (if nodemon/ts-node-dev is configured) # npm run dev8080).
API / Protocol Interaction
Clients connect to this server via HTTP GET request to establish an SSE connection. The specific endpoint depends on your deployment (e.g., http://localhost:8080/, http://<k8s-service-ip>:8080/, or through an Ingress).
Once connected, the server and client communicate using MCP messages over the SSE stream.
Available Tools
The server exposes the following tools to connected clients:
-
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,safesearchmight be supported - checksrc/services/braveSearchApi.ts)
- Output: Streams MCP messages containing search results (title, URL, snippet, etc.).
-
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.).
(Example using curl - Note: Actual MCP interaction requires a client library)
# Example: Connect to SSE endpoint (won't show MCP messages directly)
curl -N http://localhost:8080/ # Or your deployed endpoint
Client Configuration Example (Cursor)
To use this server with an MCP client like Cursor, you need to configure the client to connect to the server's SSE endpoint.
Add the following configuration to your Cursor settings (mcp.json or similar configuration file), replacing the URL with the actual address and port where your brave-search-mcp-sse server is accessible:
{
"mcpServers": {
"brave-search": {
"transport": "sse",
"url": "http://localhost:8080/sse"
}
}
}
Explanation:
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/sseis likely correct. - If running in Kubernetes, replace
localhost:8080with 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.
- If running locally via Docker (as shown in the example),
(Similar configuration steps might apply to other MCP clients that support the SSE transport, like recent versions of Claude Desktop, but refer to their specific documentation.)
Project Structure
.
├── Dockerfile # Container build definition
├── helm/ # Helm chart for Kubernetes deployment
│ └── brave-search-mcp-sse/
├── node_modules/ # Project dependencies (ignored by git)
├── src/ # Source code (TypeScript)
│ ├── config/ # Configuration loading
│ ├── services/ # Brave API interaction logic
│ ├── tools/ # Tool definitions for MCP
│ ├── transport/ # SSE/MCP communication handling
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ └── index.ts # Main application entry point
├── dist/ # Compiled JavaScript output (ignored by git)
├── package.json # Project metadata and dependencies
├── tsconfig.json # TypeScript compiler options
├── .env.example # Example environment file
├── .gitignore
└── README.md # This file
Contributing
Contributions are welcome! Please feel free to submit a Pull Request with your changes. Ensure your code adheres to the existing style and includes tests where applicable. I will review PRs as time permits.
License
This MCP server is licensed under theMIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.