Brave Search MCP/SSE Conduit

An implementation adhering to the Model Context Protocol (MCP) leveraging Server-Sent Events (SSE) to interface with the Brave Search API. This service delivers unified access to global web data and geographic search results, presented via a continuous stream to LLMs and other compatible consumers.

Conceptual Overview

This application functions as a dedicated tool provider for Large Language Models that recognize the Model Context Protocol standard. It exposes the robust search functionalities provided by Brave through a persistent SSE stream, facilitating immediate, incremental delivery of search artifacts and operational status updates.

Core Architectural Directives:

• Centralized Access Management: Architected to centralize the management of the organizational Brave Search API credentials, enabling controlled distribution of search capabilities across numerous internal applications or consuming agents.
• Operational Visibility: Implements comprehensive audit logging to monitor query traffic, API interactions, error conditions, and rate constraints, thereby enhancing usage insights and simplifying diagnostic procedures.
• Deployment Flexibility: Supports deployment scenarios ranging from isolated private network execution to public exposure via standard mechanisms such as Kubernetes Ingress controllers or direct mapping of Docker ports.

Capabilities

• Global Web Index Querying: Interface with Brave's independent web index for informational needs, news retrieval, academic indexing, etc. Includes support for result set pagination and filtering directives.
• Geographic & Entity Search: Capability to retrieve detailed listings for commercial entities, points of interest, and geographical data (e.g., addresses, contact numbers, user ratings).
• Intelligent Redundancy: The local search mechanism automatically transitions to a refined web search query if no relevant location-specific data points are identified.
• Server-Sent Events (SSE): Utilizes SSE for high-efficiency, bi-directional (though server-initiated) data transmission, supporting real-time result streaming.
• MCP Compliance: Fully conforms to the Model Context Protocol specification for frictionless integration with compatible client frameworks.
• Containerization Ready: Includes a defined Dockerfile facilitating rapid, standardized container packaging.
• Orchestration Support: Provides a curated Helm chart for streamlined provisioning within Kubernetes environments.

Prerequisites for Deployment

Depending on the chosen deployment vector, the following components are necessary:

• Brave Search API Access Token: Mandatory for all operational setups. Refer to the 'Initiation Guide' section below.
• Docker Engine: Required if utilizing containerized deployment methods.
• Kubernetes Tooling: kubectl and Helm are necessary for cloud-native deployments via Helm.
• Development Environment (Optional): Node.js (version 22.x or newer recommended) and npm are only prerequisites for active source code modification.
• Version Control: Git is needed for source code checkout when customizing images or engaging in local development.

Initiation Guide

1. Acquiring the Brave Search API Credential

1. Register for access via the Brave Search API portal.
2. Select an appropriate subscription tier (a complimentary tier exists).
3. Generate your unique access token from the developer console.

2. Configuration Specification

The service mandates the provision of the Brave Search API credential via the BRAVE_API_KEY environment variable.

Auxiliary environment parameters (consult src/config/config.ts for complete enumeration): * PORT: The network listener socket (default value is 8080). * LOG_LEVEL: Controls the fidelity of operational verbosity (e.g., info, debug).

These settings should be exported in your runtime environment or defined within a .env file placed at the project root during local testing.

Deployment & Operationalization

Select the installation path that aligns best with your infrastructure strategy:

Path 1: Docker Execution (Recommended for Production Staging)

Prerequisites: Operational Docker runtime.

1. Secure API Token: Complete step 1 from the 'Initiation Guide'.
2. Fetch Image: Retrieve the latest binary from Docker Hub: bash docker pull shoofio/brave-search-mcp-sse:latest Alternatively, target a specific version tag (e.g., 1.0.10): bash docker pull shoofio/brave-search-mcp-sse:1.0.10 (Local construction is an option: Clone the repo and execute docker build -t brave-search-mcp-sse:custom .)
3. Launch Container: Execute the runtime command. Specify the desired image tag: bash docker run -d --rm \ -p 8080:8080 \ -e BRAVE_API_KEY="YOUR_API_KEY_HERE" \ -e PORT="8080" # Optional port override # -e LOG_LEVEL="info" # Optional logging level setting --name brave-search-gateway \ shoofio/brave-search-mcp-sse:latest # Or your chosen tag This command initiates the service in detached mode, exposing container port 8080 to host port 8080.

Path 2: Kubernetes Provisioning (Via Helm)

Prerequisites: Configured kubectl access to the cluster, installed Helm utility.

1. Secure API Token: Complete step 1 from the 'Initiation Guide'.
2. Integrate Helm Repository: Register the official source: bash helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update
3. Establish API Key Secret (Best Practice): Generate a protected secret within the destination cluster namespace: bash kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace>
4. Deploy Chart: Install the package, referencing the created secret: bash helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.existingSecret=brave-search-secret # Optionally enforce a version: --version 1.0.10 Alternatively, insecure inline configuration: bash helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.apiKey="YOUR_API_KEY_HERE"

5. Tuning Parameters: Customization is achieved by overriding defaults. Define settings in a YAML file (e.g., prod-config.yaml) and reference it during installation: helm install ... -f prod-config.yaml.

   Review the canonical source file, ./helm/brave-search-mcp-sse/values.yaml, for a complete catalog of configurable parameters and their default states.

Path 3: Local Runtime Environment Setup

Prerequisites: Node.js/npm (>=v22.x), Git.

1. Secure API Token: Complete step 1 from the 'Initiation Guide'.
2. Clone Repository: Fetch the project source code: bash git clone <repository_url> # Substitute with the actual URL cd brave-search-mcp-sse
3. Dependency Installation: Install required packages: bash npm install
4. Environment Variable Definition: Create a configuration file named .env in the root directory: env BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug
5. Source Compilation: Translate TypeScript to executable JavaScript: bash npm run build
6. Service Launch: Initiate the process: bash npm start # For active development with hot-reloading, use 'npm run dev' if configured. The gateway will commence listening on the designated port (default 8080).

Protocol Interaction Specification

Client consumption mandates an HTTP GET request directed at the server's designated SSE path to establish the persistent stream. The exact URI hinges on the deployment context (e.g., http://localhost:8080/ or the Ingress hostname).

Once the connection is live, data exchange adheres strictly to MCP messages transmitted over the SSE channel.

Exposed Toolset

The gateway presents the following functional modules to connected MCP clients:

1. brave_web_search

   • Purpose: Executes broad information retrieval against the Brave Search API.
   • Arguments (Inputs):
     • query (string, mandatory): The precise subject of the search.
     • count (integer, optional): Desired quantity of records (Range: 1 to 20; Default: 10).
     • offset (integer, optional): Starting index for pagination (Range: 0 to 9; Default: 0).
     • (Additional parameters supported by the underlying Brave API, such as language, geographic region, freshness filters, or safe-search settings, are propagated; verify source file src/services/braveSearchApi.ts for the full set.)
   • Data Flow (Output): Streams sequential MCP packets containing result metadata (e.g., hyperlink, title, contextual summary).

2. brave_local_search

   • Purpose: Queries the API for proximate business listings and geographic entities. If zero local matches are returned, it triggers an automatic fallback to the web search utility.
   • Arguments (Inputs):
     • query (string, mandatory): The localized request descriptor (e.g., "pharmacy nearby", "eateries downtown").
     • count (integer, optional): Maximum result cardinality (Range: 1 to 20; Default: 5).
   • Data Flow (Output): Streams MCP messages populated with specific commercial attributes (name, physical location, contact details, rating scores, etc.).

(Note: Direct raw curl interaction is illustrative only, as true MCP conversation requires a specialized client library.)

# Conceptual connection test to the SSE endpoint
curl -N http://localhost:8080/ # Replace with live endpoint URI

Client Integration Blueprint (e.g., Cursor)

To enable an MCP consumer like Cursor to interface with this gateway, the client's configuration must specify the SSE endpoint URI. Update your client's configuration file (often mcp.json or equivalent), substituting the URL below with your accessible server address:

{
  "mcpServers": {
    "brave-search-connector": {
      "transport": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

Configuration Rationale:

• transport: Must be explicitly set to "sse".
• url: This URI is critical. If running locally via Docker as demonstrated, http://localhost:8080/sse is typically correct. For Kubernetes deployments, this must resolve to the cluster service IP/DNS or the external Ingress hostname targeting the server's listening port 8080, terminating at the /sse path.

(Configuration procedures for other MCP clients supporting the SSE transport mechanism should follow their specific documentation.)

Source Layout Reference

.
├── Dockerfile             # Container build manifest
├── helm/                  # Kubernetes Helm deployment package
│   └── brave-search-mcp-sse/
├── node_modules/        # Project dependencies (omitted from version control)
├── src/                   # Primary source code (TypeScript)
│   ├── config/            # Environment variable handling and setup
│   ├── services/          # Abstraction layer for Brave API calls
│   ├── tools/             # Definitions of exposed MCP tools
│   ├── transport/         # Logic governing SSE/MCP stream fidelity
│   ├── types/             # Custom TypeScript interface definitions
│   ├── utils/             # Shared helper functions
│   └── index.ts           # Application startup execution point
├── dist/                  # Transpiled JavaScript output (omitted from version control)
├── package.json           # Project manifest and dependency listing
├── tsconfig.json          # TypeScript compiler configuration
├── .env.example           # Template for environment configuration
├── .gitignore
└── README.md              # This documentation file

Collaboration Guidelines

Submissions via Pull Request are actively encouraged. Kindly ensure that all new code aligns with the project's established style conventions and includes relevant unit tests. Review cycles will be conducted based on developer availability.

Licensing

This MCP service is distributed under theMIT License. This grants users broad freedoms to utilize, adapt, and redistribute the software, contingent upon adherence to the terms specified in the MIT License document.