brave

Brave Search MCP 服务

一种 MCP 服务实现，可集成 Brave Search API，提供全面的搜索功能，包括网页搜索、本地商家搜索、地点搜索、图片搜索、视频搜索、新闻搜索、大模型上下文和 AI 驱动的摘要。本项目支持 STDIO 和 HTTP 传输方式，默认模式为 STDIO。

迁移

1.x 到 2.x

默认传输方式现在为 STDIO

为遵循既有 MCP 约定，服务现在默认使用 STDIO。如果要继续使用 HTTP，需要将 BRAVE_MCP_TRANSPORT 环境变量设为 http，或在启动服务时提供运行时参数 --transport http。

brave_image_search 的响应结构

MCP 服务的 1.x 版本会在图片 URL 的同时返回经过 base64 编码的图片数据。这会大幅拖慢响应速度，并不必要地占用会话上下文。2.x 版本移除了经过 base64 编码的数据，并返回一个更接近原始 Brave Search API 响应的响应对象。更新后的输出架构定义在 src/tools/images/schemas/output.ts 中。

工具

网页搜索（brave_web_search）

执行全面的网页搜索，支持丰富的结果类型和高级筛选选项。

参数：

• query（string，必需）：搜索词（最多 400 个字符、50 个词）
• country（string，可选）：国家/地区代码（默认值："US"）
• search_lang（string，可选）：搜索语言（默认值："en"）
• ui_lang（string，可选）：界面语言（默认值："en-US"）
• count（number，可选）：每页结果数（1-20，默认值：10）
• offset（number，可选）：分页偏移量（最大值：9，默认值：0）
• safesearch（string，可选）：内容筛选（"off"、"moderate"、"strict"，默认值："moderate"）
• freshness（string，可选）：时间筛选（"pd"、"pw"、"pm"、"py" 或日期范围）
• text_decorations（boolean，可选）：包含高亮标记（默认值：true）
• spellcheck（boolean，可选）：启用拼写检查（默认值：true）
• result_filter（array，可选）：筛选结果类型（默认值：["web", "query"]）
• goggles（array，可选）：自定义重新排序定义
• units（string，可选）：计量单位（"metric" 或 "imperial"）
• extra_snippets（boolean，可选）：获取额外摘要片段（仅限 Pro 方案）
• summary（boolean，可选）：启用摘要键生成，以供 AI 摘要使用

本地搜索（brave_local_search）

搜索本地商家和地点，并提供评分、营业时间和 AI 生成的描述等详细信息。

参数：

• 与 brave_web_search 相同，并自动进行位置筛选
• 自动在 result_filter 中包含 "web" 和 "locations"

**注意：**完整的本地搜索功能需要 Pro 方案。否则会回退到网页搜索。

视频搜索（brave_video_search）

搜索视频，并提供全面的元数据和缩略图信息。

参数：

• query（string，必需）：搜索词（最多 400 个字符、50 个词）
• country（string，可选）：国家/地区代码（默认值："US"）
• search_lang（string，可选）：搜索语言（默认值："en"）
• ui_lang（string，可选）：界面语言（默认值："en-US"）
• count（number，可选）：每页结果数（1-50，默认值：20）
• offset（number，可选）：分页偏移量（最大值：9，默认值：0）
• spellcheck（boolean，可选）：启用拼写检查（默认值：true）
• safesearch（string，可选）：内容筛选（"off"、"moderate"、"strict"，默认值："moderate"）
• freshness（string，可选）：时间筛选（"pd"、"pw"、"pm"、"py" 或日期范围）

图片搜索（brave_image_search）

搜索图片，并返回包含 URL、尺寸和置信度分数的元数据。

参数：

• query（字符串，必填）：搜索词（最多 400 个字符、50 个单词）
• country（字符串，可选）：国家代码（默认值："US"）
• search_lang（字符串，可选）：搜索语言（默认值："en"）
• count（数字，可选）：每页结果数（1-200，默认值：50）
• safesearch（字符串，可选）：内容过滤（"off"、"strict"，默认值："strict"）
• spellcheck（布尔值，可选）：启用拼写检查（默认值：true）

新闻搜索（brave_news_search）

搜索最新新闻文章，并提供时效控制和突发新闻标记。

参数：

• query（字符串，必填）：搜索词（最多 400 个字符、50 个单词）
• country（字符串，可选）：国家代码（默认值："US"）
• search_lang（字符串，可选）：搜索语言（默认值："en"）
• ui_lang（字符串，可选）：界面语言（默认值："en-US"）
• count（数字，可选）：每页结果数（1-50，默认值：20）
• offset（数字，可选）：分页偏移量（最大值：9，默认值：0）
• spellcheck（布尔值，可选）：启用拼写检查（默认值：true）
• safesearch（字符串，可选）：内容过滤（"off"、"moderate"、"strict"，默认值："moderate"）
• freshness（字符串，可选）：时间筛选（默认值："pd"，表示过去 24 小时）
• extra_snippets（布尔值，可选）：获取额外摘要片段（仅限 Pro 方案）
• goggles（数组，可选）：自定义重新排序规则

摘要搜索（brave_summarizer）

使用 Brave 的摘要 API，根据网页搜索结果生成 AI 摘要。

参数：

• key（字符串，必填）：网页搜索结果中的摘要密钥（在网页搜索中使用 summary: true）
• entity_info（布尔值，可选）：包含实体信息（默认值：false）
• inline_references（布尔值，可选）：添加来源 URL 引用（默认值：false）

**用法：**先使用 summary: true 执行网页搜索，然后将返回的摘要密钥与此工具配合使用。

地点搜索（brave_place_search）

使用 Brave Place Search API 搜索指定地理区域内的兴趣点（POI）。返回丰富的结构化地点数据，包括名称、地址、营业时间、联系信息、评分、照片、类别和时区。

参数：

• query（string，可选）：用于细化 POI 搜索的查询字符串（最多 400 个字符、50 个词）。省略时，返回所提供区域内的常规兴趣点。
• latitude（number，可选）：搜索中心的纬度（-90 到 90）。通常与 longitude 配合使用。
• longitude（number，可选）：搜索中心的经度（-180 到 180）。通常与 latitude 配合使用。
• location（string，可选）：地点字符串，可替代 latitude/longitude。对于美国地点，建议使用 <city> <state> <country name> 格式（例如，san francisco ca united states）；对于美国以外的地点，使用 <city> <country name> 格式（例如，tokyo japan）。
• radius（number，可选）：以米为单位的搜索半径，围绕所提供的坐标计算。省略时，将进行全球搜索。
• count（number，可选）：返回结果数量（1-50，默认值为 20）。
• country（string，可选）：两位字母的国家/地区代码（默认值为 US）。
• search_lang（string，可选）：搜索语言（默认值为 en）。
• ui_lang（string，可选）：界面语言（默认值为 en-US）。
• units（string，可选）：距离单位（metric 或 imperial，默认值为 metric）。
• safesearch（string，可选）：安全搜索级别（off、moderate、strict，默认值为 strict）。
• spellcheck（boolean，可选）：是否对查询进行拼写检查（默认值为 true）。
• geoloc（string，可选）：用于细化结果的可选地理位置令牌。

可选请求标头：

• api-version（string，可选）：Brave API 版本（YYYY-MM-DD）
• accept（string，可选）：响应媒体类型（application/json 或 */*）
• cache-control（string，可选）：使用 no-cache 请求最新内容
• user-agent（string，可选）：发起请求的用户代理

LLM 上下文（brave_llm_context）

获取预先提取的网页内容，针对 AI Agent、大模型事实依据和 RAG 工作流进行了优化。

参数：

• query（字符串，必填）：搜索查询（最多 400 个字符、50 个词）
• country（字符串，可选）：搜索国家代码
• search_lang（字符串，可选）：搜索语言代码
• count（数字，可选）：纳入考量的搜索结果上限（1-50）
• spellcheck（布尔值，可选）：启用拼写检查
• maximum_number_of_urls（数字，可选）：纳入的 URL 上限（1-50）
• maximum_number_of_tokens（数字，可选）：上下文令牌数的大致上限（1024-32768）
• maximum_number_of_snippets（数字，可选）：纳入的片段上限（1-256）
• context_threshold_mode（字符串，可选）：阈值模式（"disabled"、"strict"、"lenient"、"balanced"）
• maximum_number_of_tokens_per_url（数字，可选）：每个 URL 的令牌数上限（512-8192）
• maximum_number_of_snippets_per_url（数字，可选）：每个 URL 的片段数上限（1-100）
• goggles（字符串或数组，可选）：用于自定义重新排序的 Goggle URL 或定义
• freshness（字符串，可选）：时间筛选器（"pd"、"pw"、"pm"、"py" 或日期范围）
• enable_local（布尔值，可选）：启用本地召回
• enable_source_metadata（布尔值，可选）：包含来源元数据增强

可选请求标头：

• x-loc-lat（数字，可选）：客户端纬度（-90 到 90）
• x-loc-long（数字，可选）：客户端经度（-180 到 180）
• x-loc-city（字符串，可选）：客户端所在城市名称
• x-loc-state（字符串，可选）：客户端所在州或地区代码
• x-loc-state-name（字符串，可选）：客户端所在州或地区名称
• x-loc-country（字符串，可选）：客户端所在国家代码
• x-loc-postal-code（字符串，可选）：客户端邮政编码
• api-version（字符串，可选）：Brave API 版本（YYYY-MM-DD）
• accept（字符串，可选）：响应媒体类型（"application/json" 或 "/"）
• cache-control（字符串，可选）：使用 no-cache 请求最新内容
• user-agent（字符串，可选）：发起请求的用户代理

配置

获取 API 密钥

1. 注册 Brave Search API 账户
2. 选择套餐：
   • Search：为聊天机器人和 Agent 生成答案提供所需的实时搜索数据。完整的搜索结果（URL、文本、新闻、图片等），并附带针对 AI 优化的大模型上下文。
   • Answers：针对任何问题生成摘要式完整答案。答案以一次或多次搜索为依据，以提高准确性并减少幻觉。
3. 在开发者控制面板中生成 API 密钥

环境变量

服务支持以下环境变量：

• BRAVE_API_KEY：你的 Brave Search API 密钥（必填，除非已设置 BRAVE_API_KEY_FILE）
• BRAVE_API_KEY_FILE：包含 Brave Search API 密钥的文件路径。设置后，其优先级高于 BRAVE_API_KEY。适用于 Docker secrets 及类似的挂载密钥配置。
• BRAVE_MCP_TRANSPORT：传输模式（"http" 或 "stdio"，默认值："stdio"）
• BRAVE_MCP_PORT：HTTP 服务端口（默认值：8080）
• BRAVE_MCP_HOST：HTTP 服务主机（默认值："127.0.0.1"）。默认仅绑定到环回地址；设置为 "0.0.0.0" 可让服务在所有接口上公开（在容器内和 Amazon Bedrock AgentCore 上为必需设置）。仅在受信任的网络中这样做，因为 HTTP 端点未经身份验证。
• BRAVE_MCP_ALLOWED_ORIGINS：允许用于 HTTP 传输的其他 Origin 标头值列表，以空格或逗号分隔。始终允许环回来源；为防止 DNS 重绑定，携带其他任何 Origin 的浏览器请求都会被拒绝，并返回 HTTP 403。基于浏览器的客户端需要从实际域名访问时，请设置此项。
• BRAVE_MCP_ALLOWED_HOSTS：允许出现在 HTTP 传输 Host 标头中的主机名列表，以空格或逗号分隔。匹配时仅检查主机名，且不区分大小写；条目中可包含数字端口（例如 mcp.example.com:8080），但匹配时会忽略端口。此项为可选的纵深防御设置，需主动启用：未设置时（默认），不会验证 Host 标头，因此不会影响反向代理和自定义域名部署。设置后，仅接受环回主机和列出的主机名；其他任何 Host（包括格式错误或非数字的端口）都会被拒绝，并返回 HTTP 403。
• BRAVE_MCP_LOG_LEVEL：所需的日志级别（"debug"、"info"、"notice"、"warning"、"error"、"critical"、"alert" 或 "emergency"，默认值："info"）
• BRAVE_MCP_ENABLED_TOOLS：使用时，指定受支持工具的空格分隔白名单
• BRAVE_MCP_DISABLED_TOOLS：使用时，指定受支持工具的空格分隔黑名单
• BRAVE_MCP_STATELESS：HTTP 无状态模式（默认值："true"）。在 Amazon Bedrock Agentcore 上运行时，请设置为 "true"。

命令行选项

node dist/index.js [options]

Options:
  --brave-api-key <string>        Brave API key
  --brave-api-key-file <string>   Path to file containing Brave API key
  --transport <stdio|http>    Transport type (default: stdio)
  --port <number>             HTTP server port (default: 8080)
  --host <string>             HTTP server host (default: 127.0.0.1)
  --allowed-origins <origins...>  Allowed Origin header values for HTTP transport (DNS rebinding protection)
  --allowed-hosts <hosts...>  Allowed Host header values for HTTP transport (opt-in DNS rebinding protection)
  --logging-level <string>    Desired logging level (one of _debug_, _info_, _notice_, _warning_, _error_, _critical_, _alert_, or _emergency_)
  --enabled-tools             Tools whitelist (only the specified tools will be enabled)
  --disabled-tools            Tools blacklist (included tools will be disabled)
  --stateless  <boolean>      HTTP Stateless flag

安装

在 Claude Desktop 中使用

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

Docker

{
  "mcpServers": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

NPX

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "http"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

在 VS Code 中使用

如需快速安装，请使用下方的一键安装按钮：

如需手动安装，请将以下内容添加到 User Settings (JSON) 或 .vscode/mcp.json：

Docker

{
  "inputs": [
    {
      "password": true,
      "id": "brave-api-key",
      "type": "promptString",
      "description": "Brave Search API Key",
    }
  ],
  "servers": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "${input:brave-api-key}"
      }
    }
  }
}

NPX

{
  "inputs": [
    {
      "password": true,
      "id": "brave-api-key",
      "type": "promptString",
      "description": "Brave Search API Key",
    }
  ],
  "servers": {
    "brave-search-mcp-server": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": {
        "BRAVE_API_KEY": "${input:brave-api-key}"
      }
    }
  }
}

在 fx 中使用

将以下内容添加到 ~/.fx/mcp.json；如果文件不存在，请先创建：

Docker

{
  "mcp": {
    "brave-search": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "BRAVE_API_KEY", "docker.io/mcp/brave-search"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

NPX

{
  "mcp": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

启动 fx；如果它已在运行，请输入 /mcp reload。要验证连接，请输入 /mcp list。

构建

Docker

docker build -t mcp/brave-search:latest .

本地构建

npm install
npm run build

开发

先决条件

• Node.js 22.x 或更高版本
• npm
• Brave Search API 密钥

设置

1. 克隆仓库：

git clone https://github.com/brave/brave-search-mcp-server.git
cd brave-search-mcp-server

2. 安装依赖：

npm install

3. 构建项目：

npm run build

通过 Claude Desktop 测试

在 claude_desktop_config.json 中添加对本地构建的引用：

{
  "mcpServers": {
    "brave-search-dev": {
      "command": "node",
      "args": ["C:\\GitHub\\brave-search-mcp-server\\dist\\index.js"], // Verify your path
      "env": {
        "BRAVE_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

通过 MCP Inspector 测试

Inspector 需要 Node 22.19 或更高版本。

STDIO — Inspector 会自行启动服务，因此只需一个终端：

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

HTTP — Inspector 会连接到一个 URL，因此服务必须已在监听：

# terminal 1
npm run serve:http

# terminal 2
npm run inspector:http

serve:http 会构建服务、绑定到 127.0.0.1:8080，并从 .env 读取 BRAVE_API_KEY。

可用脚本

• npm run build：构建 TypeScript 项目

• npm run watch：监视更改并重新构建

• npm test：运行测试套件

• npm run format：使用 Prettier 格式化代码

• npm run format:check：检查代码格式

• npm run prepare：格式化并构建（在 npm install 时自动运行）

• npm run serve:http：构建后，通过 HTTP 在 http://127.0.0.1:8080/mcp 提供服务

• npm run inspector：启动 MCP Inspector 实例

• npm run inspector:http：针对 http://127.0.0.1:8080/mcp 启动 MCP Inspector

Docker Compose

使用 Docker 进行本地开发：

docker-compose up --build

启动服务栈前，请在 shell 或 .env 文件中设置 BRAVE_API_KEY（或 BRAVE_API_KEY_FILE）。默认的 docker-compose.yml 也支持 BRAVE_API_KEY_FILE，前提是指定的路径在容器内有效（例如，通过绑定挂载或 Docker secret 提供）。

Docker Compose secrets（可选）

若要避免将 API 密钥放入环境变量中，可以使用 Docker Compose secrets。服务端会从 BRAVE_API_KEY_FILE 指定的路径读取密钥，该路径必须在容器内存在。

1. 复制示例密钥文件并添加你的密钥：

cp secrets/brave_api_key.txt.example secrets/brave_api_key.txt

2. 使用可选的 secrets 覆盖配置启动服务栈：

docker compose -f docker-compose.yml -f docker-compose.secrets.example.yml up --build

该覆盖配置会将 secret 挂载到 /run/secrets/brave_api_key，并相应设置 BRAVE_API_KEY_FILE。完整配置请参见 docker-compose.secrets.example.yml。

许可证

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