为Claude Code集成Brave搜索：基于MCP协议的实时信息获取方案

1. 项目概述：为Claude Code打造一个“全视之眼”

如果你和我一样，日常重度依赖Claude Code来辅助编程、查阅文档、解决技术问题，那你一定体会过它的一个核心痛点：信息滞后。Claude的知识库有截止日期，对于瞬息万变的技术世界，比如昨天刚发布的某个框架新版本特性，或者今天某个云服务商宕机的具体影响，它往往无能为力。我们需要的，是让这位强大的AI助手能“看到”并理解当下的互联网。

这就是我开发Argus的初衷。Argus是一个基于Model Context Protocol（MCP）的服务器，它充当了Claude Code与Brave Search API之间的桥梁。简单来说，它让Claude Code拥有了实时、精准的网页搜索能力。你可以直接在Claude Code的对话窗口里说：“帮我搜索一下今天关于React Server Components性能优化的最新文章”，或者“找几张适合做登录页背景的极简风格图片”，Claude就能通过Argus调用Brave搜索，并将结构化的结果融入它的思考过程，给出结合了实时信息的答案。

项目命名为“Argus”（阿格斯），源自希腊神话中那位拥有一百只眼睛的巨人，有些眼睛永远醒着，有些则休息，这使他成为完美的守卫者。这个名字完美契合了Brave Search的核心机制——它不依赖于谷歌或必应的索引，而是通过自己独立的爬虫网络，从无数个视角持续地观察和编录整个互联网。Argus服务器，正是将这种“全视”的能力，安全、高效地注入到你的AI工作流中。

2. 核心设计思路与架构解析

在动手编码之前，我花了相当长时间来思考整个系统的设计。市面上并非没有现成的搜索MCP服务器，Brave官方也提供了自己的版本。但经过仔细评估，我发现它们要么功能受限，要么与我的使用习惯和需求不符。因此，我决定从零开始，打造一个更贴合开发者实际工作流、更透明、也更“经济”的解决方案。

2.1 为什么选择Brave Search API？

首先，是搜索服务提供商的选择。我对比了多个选项，最终锁定Brave Search，主要基于以下几点考量：

1. 独立性与隐私：Brave拥有自己的搜索索引，不依赖于谷歌或必应。这意味着其搜索结果更具独立性，避免了主流搜索引擎可能存在的“信息茧房”或商业排名干扰。同时，Brave浏览器以隐私保护著称，其搜索API也继承了这一理念，默认不追踪用户。
2. 慷慨的免费额度：对于个人开发者和小型项目，成本是必须考虑的因素。Brave Search API为“Data for Search”等核心计划提供了每月2000次请求的免费额度，并且速率限制（1次/秒）对于非高频的AI辅助搜索场景来说完全够用。这比许多其他商业API的免费门槛要友好得多。
3. 功能全面且结构清晰：其API不仅提供网页搜索，还细分出图片、视频、新闻、自动补全、拼写检查等多个端点，返回的JSON数据结构化程度高，非常容易被AI模型解析和理解。这对于构建一个功能丰富的MCP服务器至关重要。

2.2 为什么不用官方Brave Search MCP Server？

这是一个关键决策点。Brave官方确实提供了一个MCP服务器，但经过测试，我发现它存在几个不符合我预期的地方：

• 强制付费计划：官方服务器似乎设计为支持所有付费计划，对于只想依赖免费额度的用户不够友好。我的目标是最大化利用免费资源。
• 响应过度修剪：官方服务器返回给AI的上下文是经过高度筛选和修剪的。而我更倾向于将完整的、原始的API响应（当然是结构化的JSON）提供给Claude Code。我相信以Claude的推理能力，它完全有能力从丰富的信息中提取最关键的部分，有时那些“次要”的元数据反而能提供意想不到的上下文。
• 技术栈偏好：官方服务器基于Node.js。而我更擅长并偏好使用Python进行后端开发。使用熟悉的语言能让我更快速地迭代、调试和部署。

因此，Argus的定位非常明确：一个用Python编写、专注于免费计划、提供原始API数据、为Claude Code深度优化的Brave搜索网关。

2.3 核心架构：双密钥与无状态设计

Argus的架构核心是安全和清晰。我设计了一套“双密钥”系统，这可能是整个项目中最值得细说的设计决策。

通常，我们会把API密钥放在环境变量里，服务启动时加载，然后所有请求都用这个密钥。但这样做有几个问题：1) 密钥长期驻留在容器内存中；2) 无法灵活地为不同功能（搜索、AI增强、拼写检查）使用不同的密钥；3) 密钥轮换或临时禁用某个功能比较麻烦。

Argus的解决方案如下：

• 启动密钥（.env文件）：这个密钥（X_BRAVE_API_KEY_SEARCH）是可选的。它的唯一作用是在Docker容器启动时，调用一次Brave的用量查询接口，然后将你各个API计划的剩余额度漂亮地打印在日志里。如果没提供这个密钥，日志会显示用量为0/2000，但这完全不影响后续功能。
• 运行时密钥（.mcp.json文件）：这才是真正用于执行搜索的密钥。它们以HTTP请求头（Header）的方式，由Claude Code在每次调用工具时动态传递给Argus服务器。你可以在.mcp.json中配置多个不同的密钥，分别对应搜索、AI增强、拼写检查等不同功能。

{ "mcpServers": { "Argus": { "type": "http", "url": "http://localhost:8081/mcp", "headers": { "X-Brave-API-Key-Search": "你的搜索密钥", "X-Brave-API-Key-AI": "你的AI增强密钥（可选）", "X-Brave-API-Key-Autosuggest": "你的自动补全密钥（可选）", "X-Brave-API-Key-Spellcheck": "你的拼写检查密钥（可选）" } } } }

这样设计的好处是什么？

1. 安全性：API密钥不会持久化存储在Argus容器中。它们存在于你的本地配置文件（.mcp.json）里，并且仅通过HTTPS（如果配置了的话）或本地网络传输。容器本身是无状态的。
2. 灵活性：你可以随时在Claude Code的配置中更新密钥，无需重启Argus容器。你也可以只为部分功能配置密钥，比如只提供搜索密钥，那么AI增强搜索等功能将自动不可用。
3. 清晰的责任分离：启动时检查用量是一个“管理行为”，而执行搜索是“业务行为”。将它们分开，使得系统边界更清晰，也便于后续扩展（例如，未来可以增加一个独立的管理API来查看用量，而不干扰业务流）。

这个设计让Argus变得非常轻量和安全，它只是一个纯粹的、无状态的协议转换层和路由层。

3. 从零开始：环境准备与详细部署指南

理论说完了，我们动手把它跑起来。整个过程大概需要10-15分钟，前提是你已经安装了Docker。

3.1 第一步：获取Brave Search API密钥

这是唯一需要你在第三方网站进行的操作。访问 Brave Search API 控制台 。

1. 注册与登录：使用你的Brave账户或邮箱注册登录。
2. 创建应用：在控制台内，点击“Create New App”，给你的应用起个名字，比如“My Claude Code Assistant”。
3. 订阅免费计划：在应用详情页，找到“Subscriptions”部分。你需要至少订阅“Data for Search”这个计划。点击“Subscribe”，你会看到免费套餐（Free）每月有2000次请求。这里Brave会要求你添加支付方式（信用卡或PayPal），这是为了验证身份和防止滥用，只要你不超出免费额度，就不会产生任何费用。我用了几个月，从未被扣费。
4. 生成API密钥：订阅成功后，回到“Keys”标签页，点击“Generate New Key”。系统会为你创建一个API密钥，务必立即复制并保存好，因为它只显示一次。

实操心得：建议你一次性把四个免费计划都订阅了：“Data for Search”, “Data for AI”, “Autosuggest”, “Spellcheck”。虽然核心搜索只需要第一个，但另外三个能解锁非常有用的功能（后文会详述），而且都有免费额度。反正不要钱，何乐而不为呢？为每个计划分别生成一个密钥，或者如果你愿意，也可以用一个密钥关联所有计划（在创建密钥时选择所有权限）。我更喜欢分开，这样在日志里能看到每个功能分别消耗了多少额度。

3.2 第二步：本地部署Argus服务器

拿到密钥后，剩下的就全是本地操作了。

# 1. 克隆项目仓库 git clone https://github.com/IT-Square-Plus/Argus cd Argus # 2. 复制并配置环境变量模板 cp .env.example .env

现在，用你喜欢的文本编辑器打开.env文件。你只需要关注一个关键变量：

# 可选：用于启动时显示准确的API用量。不填也能用，只是日志里用量显示为0。 X_BRAVE_API_KEY_SEARCH=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

把sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx替换成你刚刚复制的“Data for Search”计划的API密钥。其他变量如服务器端口、日志级别可以保持默认。

接下来，配置Claude Code如何连接Argus：

# 3. 复制并配置MCP客户端配置模板 cp .mcp.json.example .mcp.json

打开.mcp.json文件，这是整个配置的核心：

{ "mcpServers": { "Argus": { "type": "http", "url": "http://localhost:8081/mcp", "headers": { "X-Brave-API-Key-Search": "sk_你的搜索密钥", "X-Brave-API-Key-AI": "sk_你的AI增强密钥（可选）", "X-Brave-API-Key-Autosuggest": "sk_你的自动补全密钥（可选）", "X-Brave-API-Key-Spellcheck": "sk_你的拼写检查密钥（可选）" } } } }

• X-Brave-API-Key-Search是必须填写的，否则任何搜索功能都无法工作。
• 其他三个键是可选的。如果你订阅了对应的计划并生成了密钥，就填上去，这样就能解锁增强搜索、自动补全和拼写检查功能。

重要注意事项：.mcp.json文件通常位于你的 Claude Code 配置目录下。在 macOS 上，路径可能是~/Library/Application Support/Claude/claude_desktop_config.json，但Argus项目里的这个文件是模板。最稳妥的做法是：将配置好的Argus对象，合并到你 Claude Code 的全局MCP配置文件中。你可以打开Claude Code的设置，找到“开发者设置”或“MCP服务器”部分，通常有直接编辑配置文件的入口。将上面这个Argus块复制到mcpServers对象里即可。

3.3 第三步：启动服务并验证

配置完成后，一键启动：

# 4. 使用Docker Compose启动容器（-d 表示后台运行） docker-compose up -d

第一次运行会拉取Python镜像并构建Argus的Docker镜像，稍等片刻。使用以下命令查看日志，确认服务已正常启动：

docker-compose logs -f

你应该能看到类似以下的输出，特别是如果正确配置了启动密钥，会打印出详细的API用量：

argus-1 | INFO: Started server process [1] argus-1 | INFO: Waiting for application startup. argus-1 | INFO: Application startup complete. argus-1 | INFO: Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit) argus-1 | INFO: 🚀 Argus MCP Server v1.0.1 is ready! argus-1 | INFO: 📊 API Usage Overview: argus-1 | INFO: 📈 Data For Search: [████████████░░░░░░░░░░░░░░░░░░░░] 150/2000 (7.5%) - 1850 remaining argus-1 | INFO: 📈 Data For AI: [██████████████████████████████████] 2000/2000 (100.0%) - 0 remaining argus-1 | INFO: 📈 Spellcheck: [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/5000 (0.0%) - 5000 remaining argus-1 | INFO: 📈 Autosuggest: [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 0/5000 (0.0%) - 5000 remaining

最后，验证健康端点：

# 5. 检查服务是否就绪 curl http://localhost:8081/ready

如果返回一个包含"status": "ready"的JSON，说明一切就绪。

3.4 第四步：在Claude Code中启用

最后一步是重启Claude Code应用，让它重新加载MCP配置，识别到新添加的Argus服务器。重启后，你可以打开Claude Code，尝试问它：“你现在有哪些工具可以用？”或者“列出你的可用工具”。Claude应该会回应，在它的工具列表里包含了search_web,search_images等来自Argus的工具。

至此，你的Claude Code就拥有了“全视之眼”。

4. 核心工具详解与高效使用技巧

Argus为Claude Code提供了多个工具，但最常用、最强大的无疑是网页搜索。理解每个工具的细节和最佳实践，能让你和Claude的协作效率倍增。

4.1search_web：你的主力信息检索工具

这是最核心的工具。当你在Claude Code中说“搜索一下关于Python异步编程的最佳实践”，Claude就会调用这个工具。

关键参数解析：

• query(必需)：你的搜索词。尽量清晰、具体。“Python异步编程”就比“异步”好得多。
• count：返回结果数量，默认10，最大20。对于一般性问题，10个足够。如果你在做深度调研，可以调到20。
• result_filter：这是控制上下文令牌消耗的阀门！这个参数决定了返回哪些类型的结果簇（cluster）。
  • "web"(默认，约3000令牌)：强烈推荐日常使用。只返回普通的网页结果，信息量适中，足够Claude提取核心内容。
  • ""(空字符串，约10000令牌)：返回所有结果类型，包括网页、新闻、视频、讨论、FAQ等。这会给Claude提供极其丰富的上下文，但代价是消耗大量令牌，可能挤占它用于分析和回答的“脑容量”。仅在你需要全方位了解一个话题时使用。
  • 其他过滤值：如"news","videos","discussions"等，或者组合如"web,news"。当你明确知道需要找特定类型的内容时使用。

使用示例与技巧：直接对Claude说：“使用search_web工具，查询‘如何在Docker中配置Redis持久化’，返回5条结果，只要网页内容。” Claude会理解并构造正确的调用。

避坑指南：不要滥用result_filter=""。10000令牌的上下文非常庞大，不仅响应慢，而且可能让Claude陷入“信息过载”，在无关细节上打转。我的经验是，95%的情况下，result_filter="web"是最佳选择。只有当Claude基于前几轮简单搜索后的回答依然显得片面时，再考虑使用全量搜索进行“深挖”。

4.2search_web_extra_snippets_for_ai：为AI特供的深度搜索

这个工具是search_web的增强版，需要你拥有“Data for AI”计划的API密钥。它的核心价值在于：为每一条搜索结果，额外提供最多5个摘要片段（snippet）。

这意味着什么？普通搜索只返回一个摘要片段。而这个工具返回的，是围绕这个网页核心内容的多个信息切片。比如，一个关于“机器学习模型部署”的页面，普通摘要可能只提到部署工具，而增强搜索的多个片段可能会分别提及：工具A的优缺点、工具B的适用场景、一个具体的Docker配置示例、关于模型监控的注意事项等等。

这为Claude带来了6倍于普通搜索的上下文素材，让它能更全面、更深入地理解目标网页的内容，从而给出更精准、更具洞察力的总结或答案。这对于研究性任务、技术方案对比、撰写综合性报告等场景，是无可替代的神器。

使用场景：“使用增强搜索，帮我找出三篇对比React和Vue在大型项目中状态管理方案的深度文章。” “用增强搜索查一下AWS Lambda最近一年新增了哪些重要特性，每篇找3条结果。”

4.3 垂直搜索三剑客：search_images,search_videos,search_news

这三个工具分别专注于图片、视频和新闻搜索。它们的存在不仅仅是为了功能完整，更关乎“AI节省策略”——这是我为Argus设计的一个核心优化逻辑。

问题来了：当我对Claude说“找一张可爱的猫猫图片”时，Claude有两个选择：

1. 调用通用的search_web或search_web_extra_snippets_for_ai，并尝试从网页结果中识别出图片。
2. 调用专门的search_images工具。

显然，第二个选择更高效、结果更精准。但这里有一个成本考量：search_web消耗的是“Data for Search”计划的额度，而search_web_extra_snippets_for_ai消耗的是更“宝贵”的“Data for AI”计划额度（虽然免费，但你可能想把它留给更需要深度分析的文本搜索）。

AI节省策略如何工作？Argus在后台实现了一套智能路由逻辑。当Claude调用search_images,search_videos,search_news时，服务器会先检查你的API用量情况：

1. 如果“Data for AI”额度剩余 > 50%：说明你的AI增强搜索额度还很充裕。此时，Argus会优先使用“Data for Search”计划的密钥来执行这次图片/视频/新闻搜索。目的是节省“Data for AI”的额度，留给真正的增强文本搜索。
2. 如果“Data for AI”额度不足50%，但“Data for Search”额度剩余 ≥ 10%：继续使用“Data for Search”密钥。
3. 如果“Data for Search”额度剩余 < 10%：哎呀，通用搜索额度快用完了，得省着点。这时，Argus才会转而使用“Data for AI”计划的密钥来执行这次垂直搜索。

这个策略的逻辑是：在大部分情况下，用通用的搜索额度来处理多媒体的查询，把更“高级”的AI额度留给更需要它的文本深度分析任务。你可以在Docker容器的日志中清晰地看到这个决策过程：

INFO - 🖼️ search_images called: query='cute cat', count=3 INFO - 🧠 AI-Saving Policy: AI has 92.8% remaining (>50%) → Using Search to save AI INFO - 🔑 Using Data For Search key ... INFO - 📊 Used 1 request from Data For Search quota

给你的建议：在向Claude描述搜索意图时，可以稍微具体一点。例如，“用search_images工具找三张展示现代UI设计的截图”就比“找点UI设计图片”更好，后者可能会让Claude犹豫该用哪个工具。

4.4 辅助工具：suggest与spellcheck

这两个工具需要额外的API计划，但能显著提升交互体验。

• suggest(自动补全)：当你输入一个不完整或常见的查询词时，Claude可以调用此工具获取补全建议，从而帮你优化搜索词。例如，你输入“Py”，它可能建议“Python tutorial”、“PyTorch”、“Pygame”。
• spellcheck(拼写检查)：对于非母语使用者尤其有用。它能纠正查询词中的拼写错误，确保搜索的准确性。

它们通常由Claude在后台智能调用，你无需显式指定。

5. 高级配置、监控与故障排查

当服务稳定运行后，你可能需要关注用量、调整配置，或者解决一些常见问题。

5.1 深入理解配置文件

除了基本的密钥配置，.env文件中还有一些有用的参数：

# MCP Server Configuration MCP_SERVER_HOST=0.0.0.0 # 监听所有网络接口。如果只在本地使用，可改为127.0.0.1以增强安全。 MCP_SERVER_PORT=8081 # 服务端口，如果冲突可以修改。 LOG_LEVEL=INFO # 日志级别。DEBUG会打印所有HTTP请求/响应细节，用于深度调试，但日志量巨大。 # Free Plan Limits (for usage tracking) # 这些数字用于在日志中绘制进度条，与实际API限额一致，一般无需修改。 DATA_FOR_SEARCH_FREE_PLAN_MAX_USAGE=2000 DATA_FOR_AI_FREE_PLAN_MAX_USAGE=2000

5.2 健康检查与用量监控

Argus提供了两个HTTP端点，非常适合集成到你的监控系统或简单的运维脚本中。

• GET /health(存活探针)：返回简单的存活状态。Kubernetes或Docker Swarm等编排工具会用这个端点来判断容器是否崩溃需要重启。

  curl -s http://localhost:8081/health | jq . # 输出：{"status": "alive", "service": "Argus", "version": "1.0.1"}

• GET /ready(就绪探针)：这是更有用的端点。它不仅检查服务是否运行，还汇报其能力状态和实时API用量。这是部署后验证服务是否完全就绪的最佳方式。

  curl -s http://localhost:8081/ready | jq .

  你会得到一个详细的JSON，包含所有工具是否可用，以及各个API计划的已用量、剩余量和百分比。这个信息和你启动时在日志里看到的一致，但可以随时获取。

5.3 常见问题与解决方案实录

在开发和日常使用中，我遇到并解决了一些典型问题。这里记录下来，希望能帮你快速排雷。

问题1：Claude Code提示“无法连接到MCP服务器”或工具列表里没有Argus的工具。

• 检查步骤：
  1. 确认Argus容器在运行：docker-compose ps应显示argus服务状态为Up。
  2. 检查端口：curl http://localhost:8081/health是否能返回成功。
  3. 检查Claude配置：确保.mcp.json中的配置已正确合并到Claude Code的全局MCP配置文件，并且URL端口与Argus服务端口一致。
  4. 重启Claude Code：任何对MCP配置的修改，都必须重启Claude Desktop应用才能生效。
• 根本原因：99%的情况是Claude Code的配置文件路径不对或没有重启。

问题2：搜索返回错误，日志显示“403 Forbidden”或“Invalid API Key”。

• 检查步骤：
  1. 确认密钥有效：前往Brave API控制台，确认密钥未被撤销，且对应的订阅计划（如Data for Search）仍处于活跃状态。
  2. 检查密钥位置：确认错误是针对哪个工具。如果是所有工具都报错，检查.mcp.json中的X-Brave-API-Key-Search。如果只是search_web_extra_snippets_for_ai报错，则检查X-Brave-API-Key-AI。
  3. 检查密钥格式：确保密钥完整复制，没有多余的空格或换行。API密钥通常以sk_开头。
• 根本原因：API密钥错误、过期或没有对应功能的订阅。

问题3：用量统计在日志中始终显示为0/2000。

• 原因：你没有在.env文件中配置X_BRAVE_API_KEY_SEARCH变量，或者配置的密钥无效。这是预期行为，不影响功能！启动密钥仅用于在日志中展示用量。实际的用量扣减发生在每次通过.mcp.json中密钥发起的请求中。你可以通过调用/ready端点来查看实时用量（只要运行时密钥正确）。
• 解决方案：在.env中填入一个有效的“Data for Search”密钥，然后重启容器：docker-compose restart。

问题4：搜索速度感觉有点慢。

• 可能原因：
  1. 网络延迟：Brave的API服务器可能在海外。这是无法避免的，但通常延迟在可接受范围内（200-500ms）。
  2. 结果过滤：如果你使用了result_filter=""（全量结果），Brave API需要聚合更多数据，响应时间会显著增加。
  3. Claude处理上下文：返回的结果越多，Claude需要分析和理解的时间也越长。
• 优化建议：
  1. 默认使用result_filter="web"。
  2. 适当减少count参数，比如从10降到5。
  3. 确保你的本地网络连接稳定。

问题5：Docker容器启动失败，提示端口被占用。

• 解决方案：修改.env文件中的MCP_SERVER_PORT变量，比如改为8082，同时也要修改.mcp.json中的url为http://localhost:8082/mcp。然后重新运行docker-compose up -d。

经过几个月的持续使用和迭代，Argus已经成为了我开发工作流中不可或缺的一环。它不仅仅是一个搜索工具，更是扩展了Claude Code的能力边界，让它从一个静态的知识库，变成了一个能实时感知互联网脉搏的智能伙伴。从查询最新的错误解决方案，到寻找设计灵感，再到跟踪技术趋势，这个过程变得无比自然流畅。

这个项目的代码是完全开源的，如果你对Python、FastAPI或MCP协议感兴趣，也非常欢迎你查看源码、提出Issue甚至提交PR。未来的计划包括为API用量设置硬性上限以防止意外超支，以及完善CI/CD流程。希望Argus这只“百眼巨人”，也能为你的AI辅助编程之旅保驾护航。