使用 goose 配置 Brave Search MCP 扩展：为 AI Agent 接入网页与本地搜索能力

本文基于 goose 开源仓库中的官方接入指南撰写。goose 是一个开源的、可扩展的 AI Agent（其定位不仅是代码建议工具，还能在任意 LLM 配合下安装、执行、编辑与测试任务），支持通过扩展（Extension）体系接入外部能力。本文介绍如何把 Brave Search MCP Server 注册为 goose 扩展，让 goose 在对话中直接发起交互式的网页搜索与本地搜索；读完本文，你将掌握基于 npx 启动的 Stdio 命令行扩展的完整配置流程、BRAVE_API_KEY 环境变量的注入方式，以及这类扩展在 goose 配置文件与底层源码中的真实形态。

Brave Search MCP Server 是什么

Brave Search MCP Server 是官方发布的、基于 Model Context Protocol（MCP）协议的搜索服务器包，包名为 @modelcontextprotocol/server-brave-search。把它接入 goose 后，goose 便能在执行任务时自主调用 Brave Search API，从而具备以下搜索能力：

• Web Search（网页搜索）：支持通用查询、新闻、文章检索，并提供分页（pagination）与内容时效性（freshness）控制；
• Local Search（本地搜索）：可查找商家、餐厅、服务等带有详细信息的本地结果（需要 Pro 级别的 API Key 才能启用）；
• 灵活过滤（Flexible Filtering）：可以控制返回结果类型、安全级别（safety levels）与内容新鲜度；
• 智能降级（Smart Fallbacks）：当本地搜索没有结果时，会自动回退到网页搜索，保证查询始终有返回内容。

从 goose 的角度看，这就是一个标准的命令行扩展（Command-line Extension）：goose 通过标准输入输出（stdio）与一个本地启动的 MCP 服务器进程通信。goose 的交互式配置向导中把扩展分为三类——Built-in Extension、Command-line Extension（运行本地命令或脚本）与 Remote Extension（Streamable HTTP），而 Brave Search 属于中间这一类。

前置条件

在开始配置前，需要确认环境满足以下条件：

1. Node.js：由于服务器通过 npx 启动，系统必须先安装 Node.js；
2. Brave Search API Key：注册 Brave Search API 账户并选择一个套餐（免费档每月可查询 2000 次），然后在开发者后台生成 API Key。Key 的申请流程不涉及本仓库，请按官方指引操作。

快速安装

goose 为扩展接入提供了两条并行的快速通道：goose Desktop 图形界面与 goose CLI 命令行。

goose Desktop：一条 installer 链接完成安装

goose Desktop 支持 MCP 扩展注册协议的 goose://extension deep link。将下面的安装器链接粘贴到浏览器或 goose 桌面端即可触发安装：

goose://extension?cmd=npx&arg=-y&arg=%40modelcontextprotocol%2Fserver-brave-search&id=brave-search&name=Brave%20Search&description=Brave%20Search%20API&env=BRAVE_API_KEY%3DYour%20API%20Key

该链接等价地声明了：扩展 ID 为 brave-search，显示名为 Brave Search，描述为 Brave Search API，执行命令为 npx -y @modelcontextprotocol/server-brave-search，并要求配置环境变量 BRAVE_API_KEY。桌面端安装器会自动把这些字段写入 goose 的扩展配置。

goose CLI：一行 npx 命令

在命令行环境中，扩展对应的启动命令为：

npx -y @modelcontextprotocol/server-brave-search

goose 会在需要时以该命令拉起子进程，并通过 stdio 与它通信。

无论走哪条通道，都必须为扩展提供下面的环境变量，否则服务器无法认证请求：

BRAVE_API_KEY: <YOUR_API_KEY>

通过 goose configure 完成命令行扩展配置

除了桌面端的一键安装，goose CLI 也提供了完整的交互式配置流程。依次执行下面的步骤即可把 Brave Search 注册为一个命令行扩展。全程通过 goose configure 命令的 TUI 向导完成。

第 1 步：运行 configure 命令

goose configure

第 2 步：选择添加 "Command-line Extension"

在向导中依次选择"Add Extension（Connect to a new extension）"，然后在扩展类型中选中 Command-line Extension（即"运行本地命令或脚本"）：

  ┌   goose-configure
  │
  ◇  What would you like to configure?
  │  Add Extension (Connect to a new extension)
  │
  ◆  What type of extension would you like to add?
  │  ○ Built-in Extension
  │  ● Command-line Extension (Run a local command or script)
  │  ○ Remote Extension (Streamable HTTP)
  └

第 3 步：为扩展命名

  ◆  What would you like to call this extension?
  │  brave-search

第 4 步：输入启动命令

  ◆  What command should be run?
  │  npx -y @modelcontextprotocol/server-brave-search

第 5 步：设置工具超时时间

向导会询问 goose 在操作超时前应等待的秒数，默认值为 300 秒：

  ◆  Please set the timeout for this tool (in secs):
  │  300

第 6 步：选择是否添加描述

若选择 "Yes" 会继续提示输入扩展描述；若不需要可直接选 "No"：

  ◇  Would you like to add a description?
  │  No

第 7 步：注入 API Key 环境变量

选择添加环境变量，变量名填写 BRAVE_API_KEY，变量值粘贴你在 Brave 开发者后台申请的 Key（输入时以掩码形式显示），随后选择不再添加其他变量。完成后的交互日志大致如下：

  ◆  Would you like to add environment variables?
  │  Yes
  │
  ◇  Environment variable name:
  │  BRAVE_API_KEY
  │
  ◇  Environment variable value:
  │  ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪
  │
  ◇  Add another environment variable?
  │  No
  └  Added brave-search extension

看到 Added brave-search extension 即表示注册成功，向导会把该扩展写入 goose 的全局配置。

配置背后的源码形态：从 TUI 到扩展配置条目

goose 之所以能把这套交互流程落盘，是因为在 crates/goose/src/config/extensions.rs 中定义了完整的扩展配置读写逻辑：

• 扩展配置统一存放在全局配置的 extensions 键（EXTENSIONS_CONFIG_KEY）下，由 get_extensions_map_with_config / parse_extensions_map 解析为 IndexMap<String, ExtensionEntry>；新增扩展对应 set_extension，启用/停用对应 set_extension_enabled，删除对应 remove_extension；
• 默认超时时间常量 DEFAULT_EXTENSION_TIMEOUT: u64 = 300 定义于同文件，这正是向导中"默认 300s"的出处；
• ExtensionEntry 包含 enabled 布尔位和扁平化的 ExtensionConfig，inject_name_if_missing 会自动把配置 key 补为 name，保证旧配置也能被正确解析。

在 crates/goose/src/agents/extension.rs 中，ExtensionConfig 是一个带 #[serde(tag = "type")] 的枚举，Command-line Extension 对应的就是 Stdio 变体（#[serde(rename = "stdio")]），其关键字段与 Brave Search 场景的对应关系如下：

字段	含义	本文示例值
name	扩展标识名	brave-search
description	扩展描述（可空）	自定义描述
cmd	可执行命令	npx
args	命令行参数	["-y", "@modelcontextprotocol/server-brave-search"]
envs	注入给子进程的环境变量（兼容旧字段名 env）	BRAVE_API_KEY: <YOUR_API_KEY>
env_keys	从配置密钥库间接引用的环境变量名	可选
timeout	工具超时（秒），默认 300	300
cwd	子进程工作目录	可选

也就是说，你在向导里输入的每一项内容，最终都会序列化进全局配置文件（如 ~/.config/goose/config.yaml 或 goose.json，具体路径由 crates/goose/src/config/paths.rs 决定）中 extensions 下的一个 type: stdio 条目，形如：

extensions:
  brave-search:
    type: stdio
    name: brave-search
    description: Brave Search API
    cmd: npx
    args:
      - -y
      - "@modelcontextprotocol/server-brave-search"
    envs:
      BRAVE_API_KEY: <YOUR_API_KEY>
    timeout: 300

除了手动走向导，goose 也支持直接在配置文件中按上述结构手写扩展条目，随后通过扩展管理逻辑加载（即 crates/goose/src/agents/extension_manager.rs 中负责维护 MCP 扩展管理器并派发工具调用的部分）。运行时，goose 会以 cmd + args 启动子进程，把 envs 合并进进程环境（源码中对应 merge_environments(&envs, ...) 逻辑），并通过 stdio 完成 MCP 握手与工具调用。

实战示例：让 goose 用它筹备意大利晚宴

配置完成后，你可以直接在会话中让 goose 借助 Brave Search 完成多步、多主题的检索任务。下面是文档中给出的真实示例。

goose Prompt（用户输入）

( O)> Organize a Italian dinner party with Ian, Rizel, Ace, and Ebony. Find 3 or 4 YouTube cooking channels (with URLs) that focus on Italian cuisine for beginners, and then find one recipe (with URL) for each person to make: one salad, two entrees, and one dessert.

goose Output（goose 输出）

goose 会先声明计划，然后把任务拆解为多次 Brave Web Search 调用，分别检索"适合初学者的意餐 YouTube 频道""意式沙拉食谱""意式主菜食谱"与"意式甜点食谱"：

I'll help you organize the Italian dinner party and search for appropriate cooking resources and recipes. Let me break this down into parts.

First, let's search for some beginner-friendly Italian cooking YouTube channels:

Brave Web Search
query: best youtube channels italian cooking for beginners authenti...

Let me search for some specific recipes:

Brave Web Search
query: authentic italian salad recipes panzanella caprese insalata

Brave Web Search
query: authentic italian main course pasta recipes carbonara osso b...

Brave Web Search
query: authentic italian dessert recipes tiramisu panna cotta

基于检索结果，goose 会整理出一份结构化的晚宴方案（为便于阅读，原文中的具体 URL 此处从略）：

面向初学者的意大利烹饪 YouTube 频道推荐

1. Vincenzo's Plate：提供清晰的意式做法讲解，由意大利本地人运营，讲解技巧对新手友好；
2. Italia Squisita：主打传统意式食谱，常演示同一经典菜品的多种做法；
3. Giallo Zafferano：意大利最受欢迎的烹饪频道之一，覆盖大量正宗意式食谱。

每位参与者对应的菜品分工

1. Rizel — 沙拉 Course：经典 Panzanella（托斯卡纳面包番茄沙拉），以脆皮面包、番茄与新鲜罗勒为主，适合夏天；
2. Ian — 第一道主菜：正宗 Spaghetti Carbonara，罗马经典意面，用鸡蛋、pecorino 奶酪与 guanciale 制作；
3. Ace — 第二道主菜：Osso Buco alla Milanese，米兰传统炖小牛膝配 gremolata 香草碎；
4. Ebony — 甜点：经典香草 Panna Cotta，优雅顺滑且可提前制作。

成功备餐提示

• 提前观看 YouTube 频道以熟悉意餐技法；
• 动手前通读完整食谱；
• Panna Cotta 至少提前 4 小时（或前一晚）制作以便定型；
• Panzanella 建议上桌前再组装以保证最佳口感；
• Osso Buco 可提前制作并复热，隔夜风味往往更佳；
• Carbonara 应在上桌前现做并趁热立即上桌。

这个例子展示了 Brave Search 扩展的核心价值：goose 将用户的一个复合任务自动拆解为多次并行/连续的搜索意图，再对结果进行汇总、筛选与结构化输出，最终给出可直接执行的完整方案。对同样具备工具调用能力的任意 LLM 后端，这一模式都是可复用的——配置一次，goose 的所有会话就都拥有了实时联网检索能力。

小结

通过 Brave Search MCP Server，goose 获得了可靠的网页与本地实时检索能力。接入过程可以概括为三步：确认 Node.js 与 Brave Search API Key 就绪 → 通过 goose Desktop 的 installer 链接或 goose configure 向导注册名为 brave-search 的命令行扩展 → 注入 BRAVE_API_KEY 环境变量。底层来看，这就是一个 type: stdio 的扩展配置条目（见 crates/goose/src/config/extensions.rs 与 crates/goose/src/agents/extension.rs），默认 300 秒超时、环境变量注入与 stdio 通信均由 goose 的扩展管理器自动处理。若希望启用本地搜索等进阶能力，请确认你的 Brave API 套餐达到相应级别，并留意本地搜索无结果时自动回退到网页搜索的行为。