Labsco
Shoofio logo

Brave Search

★ 15

from Shoofio

An MCP server for the Brave Search API, providing web and local search capabilities via a streaming SSE interface.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#devops#git#search#monitoring#news

Brave Search MCP/SSE Server

License: MIT Docker Hub Helm Chart

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 Dockerfile for easy containerization and deployment.
  • Helm Chart: Provides a Helm chart for straightforward deployment to Kubernetes clusters.

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:

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

(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/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.

(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