Brave Search MCP/SSE 服务器

使用服务器发送事件 (SSE) 实现的模型上下文协议 (MCP) 集成了Brave Search API ，通过流接口为 AI 模型和其他客户端提供网络和本地搜索功能。

概述

该服务器充当理解模型上下文协议的大型语言模型的工具提供者。它通过 SSE 连接公开 Brave 强大的 Web 和本地搜索功能，从而实现搜索结果和状态更新的实时流式传输。

主要设计目标：

**集中访问：**设计时考虑了中心性，允许组织或个人管理单个 Brave Search API 密钥并提供对多个内部客户端或应用程序的受控访问。
**可观察性：**具有强大的日志记录功能，可跟踪请求、API 交互、错误和速率限制，提供使用情况的可见性并帮助调试。
**灵活部署：**可以在网络内私下部署，也可以选择通过 Kubernetes Ingress 或直接 Docker 端口映射等方法公开部署。

Related MCP server: MCP2Brave

特征

网络搜索：访问 Brave 的独立网络搜索索引，获取一般查询、新闻、文章等。支持分页和过滤控制。
本地搜索：查找企业、餐馆和服务，包括地址、电话号码和评级等详细信息。
智能回退：如果未找到查询的特定本地结果，本地搜索将自动回退到过滤的网络搜索。
服务器发送事件 (SSE) ：高效、实时地传输搜索结果和工具执行状态。
模型上下文协议 (MCP) ：遵循 MCP 标准，可与兼容客户端无缝集成。
Docker 支持：包含一个Dockerfile ，可轻松实现容器化和部署。
Helm Chart ：提供 Helm Chart，可直接部署到 Kubernetes 集群。

先决条件

根据您选择的部署方法，您将需要以下一些内容：

Brave Search API 密钥：所有部署方式均需使用。请参阅下方的“入门指南”。
Docker ：如果使用 Docker 部署则必需。
kubectl 和 Helm ：如果使用 Helm 部署到 Kubernetes，则需要。
Node.js 和 npm ：仅本地开发所需（建议使用 Node.js v22.x 或更高版本）。
Git ：需要克隆存储库以进行本地开发或构建自定义 Docker 镜像。

入门

1. 获取 Brave Search API 密钥

注册一个Brave Search API 帐户。
选择一个计划（提供免费套餐）。
从开发者仪表板生成您的 API 密钥。

2.配置

服务器需要通过BRAVE_API_KEY环境变量设置 Brave Search API 密钥。

其他潜在的环境变量（有关详细信息，请查看src/config/config.ts ）：

PORT ：服务器监听的端口（默认为8080 ）。
LOG_LEVEL ：日志详细程度（例如， info 、 debug ）。

在您的环境中设置这些变量或使用项目根目录中的.env文件进行本地开发。

安装和使用

选择最适合您需求的部署方法：

选项 1：Docker（推荐部署）

**先决条件：**已安装 Docker。

**获取 Brave Search API 密钥：**按照“入门”部分中的步骤操作。
**拉取 Docker 镜像：**从 Docker Hub 拉取最新镜像：
docker pull shoofio/brave-search-mcp-sse:latest
或者拉取特定的版本标签（例如1.0.10 ）：
docker pull shoofio/brave-search-mcp-sse:1.0.10
（或者，如果需要，您可以本地构建映像。克隆存储库并运行
**运行 Docker 容器：**使用您拉取的标签（例如latest或1.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
这将以分离模式运行服务器，将主机上的端口 8080 映射到容器。

选项 2：Helm（Kubernetes 部署）

先决条件： kubectl已连接到您的集群，已安装 Helm。

**获取 Brave Search API 密钥：**按照“入门”部分中的步骤操作。
添加 Helm 存储库：
helm repo add brave-search-mcp-sse https://shoofio.github.io/brave-search-mcp-sse/ helm repo update
**准备 API 密钥（推荐）：**在目标命名空间中创建 Kubernetes 密钥：
kubectl create secret generic brave-search-secret \ --from-literal=api-key='YOUR_API_KEY_HERE' \ -n <your-namespace>
安装 Helm chart： chart 版本对应应用程序版本（最新版本为1.0.10 ）。使用 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.10
或者直接提供密钥（不太安全）：
helm install brave-search brave-search-mcp-sse/brave-search-mcp-sse \ -n <your-namespace> \ --set braveSearch.apiKey="YOUR_API_KEY_HERE"
**Chart 配置：**您可以通过覆盖默认值来自定义部署。创建一个包含所需设置的 YAML 文件（例如dev-values.yaml或prod-values.yaml ），并在安装过程中使用-f标志： helm install ... -f dev-values.yaml 。
请参阅图表的默认values.yaml文件以查看所有可用的配置选项及其默认设置。

选项 3：本地开发

先决条件： Node.js 和 npm（建议使用 v22.x 或更高版本）、Git。

**获取 Brave Search API 密钥：**按照“入门”部分中的步骤操作。
克隆存储库：
git clone <repository_url> # Replace with the actual URL cd brave-search-mcp-sse
安装依赖项：
npm install
**设置环境变量：**在根目录中创建一个.env文件：
BRAVE_API_KEY=YOUR_API_KEY_HERE PORT=8080 # LOG_LEVEL=debug
构建 TypeScript 代码：
npm run build
运行服务器：
npm start # Or for development with auto-reloading (if nodemon/ts-node-dev is configured) # npm run dev
服务器将开始监听配置的端口（默认为8080 ）。

API/协议交互

客户端通过 HTTP GET 请求连接到此服务器，以建立 SSE 连接。具体端点取决于你的部署（例如， http://localhost:8080/ 、 http://<k8s-service-ip>:8080/ ，或通过 Ingress）。

一旦连接，服务器和客户端就通过 SSE 流使用 MCP 消息进行通信。

可用工具

服务器向连接的客户端公开以下工具：

brave_web_search
- 描述：使用 Brave Search API 执行常规网络搜索。
- 输入：
  - query （字符串，必需）：搜索查询。
  - count （数字，可选）：返回的结果数（1-20，默认为 10）。
  - offset （数字，可选）：分页偏移量（0-9，默认为 0）。
  - （其他 Brave API 参数，如
- 输出：包含搜索结果（标题、URL、片段等）的流式 MCP 消息。
brave_local_search
- 描述：使用 Brave Search API 搜索本地商家和地点。如果未找到本地结果，则返回网页搜索。
- 输入：
  - query （字符串，必需）：本地搜索查询（例如，“我附近的披萨”，“市中心的咖啡馆”）。
  - count （数字，可选）：最大结果数（1-20，默认 5）。
- 输出：包含本地业务详细信息（名称、地址、电话、评级等）的流式 MCP 消息。

（使用

# Example: Connect to SSE endpoint (won't show MCP messages directly) curl -N http://localhost:8080/ # Or your deployed endpoint

客户端配置示例（游标）

要将此服务器与 Cursor 等 MCP 客户端一起使用，您需要配置客户端以连接到服务器的 SSE 端点。

将以下配置添加到您的 Cursor 设置（ mcp.json或类似的配置文件）中，将 URL 替换为您的brave-search-mcp-sse服务器可访问的实际地址和端口：

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

解释：

transport ：对于此服务器，必须设置为"sse" 。
url ：这是关键部分。
- 如果通过 Docker 在本地运行（如示例所示）， http://localhost:8080/sse可能是正确的。
- 如果在 Kubernetes 中运行，请将localhost:8080替换为适当的 Kubernetes 服务地址/端口或配置为到达服务器端口 8080 的 Ingress 主机名/路径。
- 确保 URL 路径以/sse结尾。

（类似的配置步骤可能适用于支持 SSE 传输的其他 MCP 客户端，例如 Claude Desktop 的最新版本，但请参阅其具体文档。）

项目结构

. ├── 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

贡献

欢迎贡献代码！请随时提交 Pull 请求，包含您的修改。请确保您的代码遵循现有代码规范，并在适用的情况下包含测试。我会在时间允许的情况下审核 PR。

执照

此 MCP 服务器采用MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详细信息，请参阅项目仓库中的 LICENSE 文件。

Brave Search MCP Server