Brave Search MCP Server

Brave Search MCP 服务

一个 MCP 服务实现，可集成 Brave Search API，提供网页搜索、本地兴趣点搜索、视频搜索、图片搜索、新闻搜索和大模型上下文搜索功能

功能

• 网页搜索：在网页上执行常规搜索
• 图片搜索：在网页上搜索图片。
• 新闻搜索：在网页上搜索新闻
• 视频搜索：在网页上搜索视频
• 本地兴趣点搜索：搜索本地实体地点、企业、餐厅、服务等
• 大模型上下文搜索：获取并提取完整的网页内容，以便阅读和综合整理来源

工具

• brave_web_search

  • 使用 Brave 的 API 执行网页搜索
  • 输入：
    • query (string)：要在互联网上搜索的词语
    • count (number, optional)：要返回的结果数量（最多 20 个，默认 10 个）
    • offset (number, optional, default 0)：分页偏移量
    • freshness (enum, optional)：根据搜索结果的发现时间筛选结果
      • 支持以下值
        • pd：在过去 24 小时内发现。
        • pw：在过去 7 天内发现。
        • pm：在过去 31 天内发现。
        • py：在过去 365 天内发现
        • YYYY-MM-DDtoYYYY-MM-DD：自定义日期范围（例如，2022-04-01to2022-07-30）

• brave_image_search

  • 获取与查询相关的网页图片
  • 输入：
    • query (string)：要在互联网上搜索图片的词语
    • count (number, optional)：要返回的图片数量（最多 50 张，默认 10 张）

• brave_news_search

  • 在网页上搜索新闻
  • 输入：
    • query (string)：用于搜索新闻文章、热门话题或近期事件的词语
    • count (number, optional)：要返回的结果数量（最多 20 个，默认 10 个）
    • offset (number, optional, default 0)：分页的从零开始的偏移量（最多 9）
    • freshness (enum, optional)：根据搜索结果的发现时间筛选结果
      • 支持以下值
        • pd：在过去 24 小时内发现。
        • pw：在过去 7 天内发现。
        • pm：在过去 31 天内发现。
        • py：在过去 365 天内发现
        • YYYY-MM-DDtoYYYY-MM-DD：自定义日期范围（例如，2022-04-01to2022-07-30）

• brave_local_search

  • 搜索本地企业、服务和兴趣点
  • 如果初始页面未找到地点结果，则回退到 brave_web_search
  • 输入：
    • query (string)：本地搜索词
    • count (number, optional)：要返回的结果数量（最多 20 个，默认 5 个）
    • offset (number, optional, default 0)：分页的从零开始的偏移量（最多 9）

• brave_video_search

  • 在网页上搜索视频
  • 输入：
    • query：(string)：用于搜索视频的词语
    • count：(number, optional)：要返回的视频数量（最多 20 个，默认 10 个）
    • offset (number, optional, default 0)：分页的从零开始的偏移量（最多 9）
    • freshness (enum, optional)：根据搜索结果的发现时间筛选结果
      • 支持以下值
        • pd：在过去 24 小时内发现。
        • pw：在过去 7 天内发现。
        • pm：在过去 31 天内发现。
        • py：在过去 365 天内发现
        • YYYY-MM-DDtoYYYY-MM-DD：自定义日期范围（例如，2022-04-01to2022-07-30）

• brave_llm_context_search

  • 预提取的网页内容，针对 AI Agent、大模型上下文依据和 RAG 流水线进行了优化。
  • 在 compact 模式下使用 Brave 的 balanced 上下文阈值模式，在 full 模式下停用 Brave 的相关性筛选。
  • 输入：
    • query（字符串）：搜索查询。最多 400 个字符、50 个词。
    • url（字符串，可选）：可选的目标 URL。提供后，查询和 URL 会组合用于检索，并且只返回来自此确切 URL 的摘要。
    • count（数字，可选，默认值为 8）：纳入考量的搜索结果上限。最小值为 1，最大值为 50。
    • maximumNumberOfUrls（数字，可选，默认值为 8）：响应中包含的 URL 上限。最小值为 1，最大值为 50。
    • maximumNumberOfTokens（数字，可选，默认值为 2048）：返回上下文的大致令牌上限。最小值为 1024，最大值为 32768。
    • maximumNumberOfSnippets（数字，可选，默认值为 16）：所有 URL 的摘要总数上限。最小值为 1，最大值为 100。
    • maximumNumberOfTokensPerUrl（数字，可选，默认值为 512）：每个 URL 的令牌上限。最小值为 512，最大值为 8192。
    • maximumNumberOfSnippetsPerUrl（数字，可选，默认值为 2）：每个 URL 的摘要数上限。最小值为 1，最大值为 100。
    • responseMode（枚举，可选，默认值为 compact）：compact 会应用 Brave 的 balanced 相关性筛选，并在本地筛选和截断摘要。full 会停用 Brave 的相关性筛选，并返回未经本地筛选或截断的原始摘要。
    • maxSnippetChars（数字，可选，默认值为 400）：compact 模式下每条摘要的最大字符数。最小值为 80，最大值为 4000。
    • maxOutputChars（数字，可选，默认值为 8000）：compact 模式下序列化响应的大致字符数上限。最小值为 1000，最大值为 100000。

OpenAI Apps 和 MCP Apps 支持

▶️ 点击观看演示视频

此 MCP 服务现已支持 OpenAI Apps 和 MCP Apps。为每个工具启用 UI 模式后，都会显示相应的 UI 小组件，让你控制要添加到模型上下文中的内容。请参阅与 ChatGPT 搭配使用一节中的说明。

配置

获取 API 密钥

1. 注册 Brave Search API 账号
2. 选择套餐
3. 在开发者控制面板中生成 API 密钥

运行模式

默认情况下，MCP 服务以 stdio 模式运行。

BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp

启用 Streamable HTTP 模式：

BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http

默认情况下，服务监听 3001 端口。 URL 为：

http://0.0.0.0:3001/mcp

有两种配置模式：

• 环境变量模式：未设置 BRAVE_MCP_CONFIG。功能开关与之前的版本一样，取自环境变量。
• 文件模式：已设置 BRAVE_MCP_CONFIG=/path/to/config.toml。TOML 文件将成为功能设置的唯一事实来源；如有重复的功能环境变量，将忽略这些变量并显示警告。

仅限环境变量的设置

无论使用哪种模式，始终从进程环境中读取以下设置：

• BRAVE_API_KEY（必填）：Brave Search API 密钥。
• PORT（可选）：HTTP 端口（默认值：3001）。
• HOST（可选）：要绑定的接口（默认值：0.0.0.0）。
• BRAVE_MCP_CONFIG（可选）：功能设置 TOML 配置文件的绝对或相对路径。

环境模式功能设置

未设置 BRAVE_MCP_CONFIG 时，支持以下功能环境变量：

• ALLOWED_HOSTS（仅限 HTTP 模式）：以逗号分隔的允许主机名列表，用于验证 Host 标头。
  • 示例：ALLOWED_HOSTS=localhost,127.0.0.1,my-app.ngrok-free.app
  • 仅使用主机名（不含协议或路径），例如 my-app.ngrok-free.app，而非 https://my-app.ngrok-free.app/mcp
• BRAVE_MCP_POLICY_FILE：JSON 策略文件路径。
• BRAVE_MCP_POLICY_REDACT：设为 true 时，将匹配的文本替换为遮蔽内容，而非阻止它。
• BRAVE_MCP_REQUEST_LIMIT：正整数请求上限。
• BRAVE_MCP_WINDOW_SECONDS：非负整数滚动窗口大小。
• BRAVE_MCP_COOLDOWN_SECONDS：超过上限后的非负整数冷却时间。
• BRAVE_MCP_AUDIT_LOG：设为 true 时，输出审计日志。
• BRAVE_MCP_AUDIT_LOG_RAW：设为 true 时，在审计日志中包含原始查询文本。
• BRAVE_MCP_REQUIRE_JUSTIFICATION：设为 true 时，拒绝不含 justification 字符串的工具调用。

示例：

# Local only
HOST=127.0.0.1 ALLOWED_HOSTS=localhost,127.0.0.1 BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http

# Local with ngrok tunnel
HOST=127.0.0.1 ALLOWED_HOSTS=localhost,127.0.0.1,my-app.ngrok-free.app BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http --ui

文件模式（BRAVE_MCP_CONFIG）

设置 BRAVE_MCP_CONFIG 后，该文件将控制功能配置，包括 HTTP 主机允许列表。

[auth]
httpApiKey = "sk-..."
requireAuth = true
callerId = "team-a"

[auth.jwt]
jwksUri = "https://idp.example.com/.well-known/jwks.json"
audience = "brave-search-mcp"
clockSkewSeconds = 30

[auth.oauth]
issuer = "https://idp.example.com"
audience = "brave-search-mcp"
clientId = "client-123"
clientSecret = "super-secret"
verifyStrategy = "jwks"

[audit]
enabled = true
logRaw = false
hmacSecret = "audit-secret"

[policy]
file = "/etc/brave-mcp/policy.json"
redact = false

[guardrail]
requestLimit = 100
windowSeconds = 60
cooldownSeconds = 10
requireJustification = false

[server]
allowedHosts = [
  "localhost",
  "127.0.0.1",
  "my-app.ngrok-free.app",
]

注意：

• 即使在文件模式下，BRAVE_API_KEY、PORT 和 HOST 仍仅通过环境变量设置。
• 如果设置了与 BRAVE_MCP_CONFIG 同时生效的功能环境变量（例如 BRAVE_MCP_REQUEST_LIMIT 或 ALLOWED_HOSTS），启动时会警告这些变量将被忽略。
• 未知的 TOML 键也会触发警告，便于在调试运行时行为之前发现 [guardrails] 之类的拼写错误。

如需在不启动服务的情况下验证配置文件，请在构建应用工作区后使用打包的入口点：

pnpm -C apps/brave-search-mcp run build
node apps/brave-search-mcp/dist/index.js --check-config ./apps/brave-search-mcp/test/fixtures/config.valid.toml

如需在文件模式下运行已构建的本地入口点：

pnpm -C apps/brave-search-mcp run build
BRAVE_API_KEY="your_key_here" BRAVE_MCP_CONFIG="$PWD/apps/brave-search-mcp/test/fixtures/config.valid.toml" node apps/brave-search-mcp/dist/index.js --http

与 ChatGPT 搭配使用

Brave Search MCP 服务可与 ChatGPT 网页界面搭配使用。只需几步即可完成设置。

1. 在 ChatGPT 中启用开发者模式

设置 → Apps → 高级设置 → 开发者模式

此处有更多说明

2. 以 HTTP 模式和 UI 模式运行 Brave Search MCP

BRAVE_API_KEY="your_key_here" npx -y brave-search-mcp --http --ui

3. 创建本地隧道，将 MCP 服务公开给 ChatGPT

注册并配置 ngrok，免费套餐即可使用。

ngrok http 3001

记下转发 URL。

...
Forwarding                    https://john-joe-asdf.ngrok-free.dev -> http://localhost:3001
...

4. 将 Brave Search MCP 添加为 ChatGPT 连接器

打开 ChatGPT Apps 设置

点击 Apps

点击 Create Apps

填写表单时，使用第 3 步中的 URL 作为 MCP 服务 URL，并在末尾添加 /mcp。

https://john-joe-asdf.ngrok-free.dev/mcp

对于身份验证，选择“No Auth”

勾选“I understand and want to continue”复选框

然后点击 Create。

5. 使用 Brave Search MCP 服务

在 ChatGPT 界面中，点击“+”按钮，滚动到“...more”，选择新创建的 Brave Search 应用，然后输入查询。

与 Claude Code 搭配使用

Claude Code 用户可运行以下命令：

Windows：

claude mcp add-json brave-search '{"command":"cmd","args":["/c","npx","-y","brave-search-mcp"],"env":{"BRAVE_API_KEY":"YOUR_API_KEY_HERE"}}'

Linux/macOS：

claude mcp add-json brave-search '{"command":"npx","args":["-y","brave-search-mcp"],"env":{"BRAVE_API_KEY":"YOUR_API_KEY_HERE"}}'

将 YOUR_API_KEY_HERE 替换为你实际的 Brave Search API 密钥。

与 Claude Desktop 搭配使用

MCP Bundle（MCPB）

1. 从 Releases 下载 mcpb 文件
2. 使用 Claude Desktop 打开该文件 或者 前往 File -> Settings -> Extensions，然后将 .mcpb 文件拖到窗口中进行安装

Docker

1. 克隆代码仓库
2. 在代码仓库根目录构建镜像

docker build -t brave-search-mcp:latest -f apps/brave-search-mcp/Dockerfile .

3. 如果要使用 HTTP 模式，直接运行：

docker run --rm -p 3001:3001 -e BRAVE_API_KEY="YOUR_API_KEY_HERE" brave-search-mcp:latest --http

4. 对于 stdio 模式，将以下内容添加到 claude_desktop_config.json：

{
  "mcp-servers": {
    "brave-search": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "BRAVE_API_KEY",
        "brave-search-mcp"
      ],
      "env": {
        "BRAVE_API_KEY": "YOUR API KEY HERE"
      }
    }
  }
}

NPX

将以下内容添加到 claude_desktop_config.json：

{
  "mcp-servers": {
    "brave-search": {
      "command": "npx",
      "args": [
        "-y",
        "brave-search-mcp"
      ],
      "env": {
        "BRAVE_API_KEY": "YOUR API KEY HERE"
      }
    }
  }
}

与 LibreChat 搭配使用

将以下内容添加到 librechat.yaml

brave-search:
  command: sh
  args:
    - -c
    - BRAVE_API_KEY=API KEY npx -y brave-search-mcp

贡献

欢迎贡献！有关开发环境设置、monorepo 结构和发布说明，请参阅 CONTRIBUTING.md。 有关 UI 构建工作流的详细信息（包括入口点协调器），请参阅 UI Build Orchestrator。

免责声明

此库与 Brave Software 没有官方关联。它是 Brave Search API 的第三方实现，并提供 MCP 服务。

许可证

此项目采用 GNU General Public License v3.0 许可，详情请参阅 LICENSE 文件。