使用说明

👁️ Argus-Brave搜索MCP服务器

Argus是一个模型上下文协议（MCP）服务器，通过HTTP流传输提供对Brave Search API的全面访问。Argus专为Claude Code等人工智能助手设计，支持网络搜索、图像搜索、视频搜索、新闻搜索、自动补全建议和拼写检查。

这个名字来源于希腊神话。

Argus Panoptes（“All Seeing Argus”）是希腊神话中的巨人，他身上有一百只眼睛，有些眼睛总是醒着，有些眼睛睡着了，这使他成为完美的守望者。这个名字完美地反映了Brave Search的核心功能：不断收集和聚合来自网络上多个独立来源的信息。就像拥有独立警惕眼睛的阿格斯一样，Brave Search也有自己的独立索引，从无数角度同时观察和编目互联网。这个名字体现了监视、可靠性和无所不在的品质，这些品质定义了神话般的守护者和现代搜索引擎。

特性

网页搜索 -功能齐全的网络搜索，可定制结果过滤器
增强的Web搜索 -通过额外的片段获得6倍的上下文（AI计划的数据）
图像搜索 -使用元数据搜索和检索图像
视频搜索 -查找包含持续时间、观看次数和发布者信息的视频
新闻搜索 -获取带有突发新闻标志的最新新闻文章
自动完成 -查询建议和自动完成
拼写检查 -查询更正和拼写检查
实时使用情况跟踪 -监控所有计划的API配额使用情况
健康监测 -容器编排的生存性和就绪性探测

快速开始

先决条件

Docker&Docker编写 - 安装Docker
勇敢搜索API密钥 - 获取免费的API密钥
- 必修的： 搜索数据 计划（每月免费2000个请求）¹
- 可选： AI数据, 自动建议, 检查拼写 计划¹

安装

克隆存储库

git clone https://github.com/IT-Square-Plus/Argus
cd Argus

配置环境变量
```
cp .env.example .env
# Edit .env and add your Brave Search API key for startup usage tracking
```
还没有API密钥？请参阅勇敢搜索API指南¹ 获取分步说明。
配置MCP客户端（克劳德代码）
```
cp .mcp.json.example .mcp.json
# Edit .mcp.json and replace placeholder API keys with your actual keys
```
还没有API密钥？请参阅勇敢搜索API指南¹ 获取分步说明。
启动Argus集装箱
```
docker-compose up -d
```
验证服务是否就绪
```
curl http://localhost:8081/ready
```
重新启动Claude代码 加载MCP服务器

配置

环境变量（.env）

这 .env file配置Docker容器启动行为：

# MCP Server Configuration
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8081
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL

# Free Plan Limits (for usage tracking)
DATA_FOR_SEARCH_FREE_PLAN_MAX_USAGE=2000
DATA_FOR_AI_FREE_PLAN_MAX_USAGE=2000
DATA_FOR_SPELLCHECK_FREE_PLAN_MAX_USAGE=5000
DATA_FOR_AUTOSUGGEST_FREE_PLAN_MAX_USAGE=5000

# Optional: API Key for startup usage check
# This displays accurate quota info in startup logs
# Runtime tools use keys from .mcp.json (HTTP headers)
X_BRAVE_API_KEY_SEARCH=your_api_key_here

MCP客户端配置（.MCP.json）

这 .mcp.json 文件配置Claude Code以连接到Argus：

{
  "mcpServers": {
    "Argus": {
      "type": "http",
      "url": "http://localhost:8081/mcp",
      "headers": {
        "X-Brave-API-Key-Search": "your_data_for_search_api_key_here",
        "X-Brave-API-Key-AI": "your_data_for_ai_api_key_here",
        "X-Brave-API-Key-Autosuggest": "your_autosuggest_api_key_here",
        "X-Brave-API-Key-Spellcheck": "your_spellcheck_api_key_here"
      }
    }
  }
}

重要提示：

仅 X-Brave-API-Key-Search 是 必需的 核心功能
其他API密钥包括 可选的 并启用其他功能
如果有多个计划，则可以对多个标头使用相同的API键
API密钥通过HTTP头提供（per-request，不存储在容器中）

🔧 可用工具

搜索web

使用Brave search API进行完整的网络搜索。

关键参数：

query -搜索查询（必填）
count -结果数（默认值：10，最大值：20）
result_filter -按类型筛选结果：
- "web" （默认值，约3k个令牌）-仅限Web结果✅ 推荐
- "" （所有集群，约10k个令牌）-所有结果类型
- "news" -仅新闻文章
- "videos" -仅视频
- "discussions" -仅限论坛讨论
- "faq" -仅问答结果
- "infobox" -仅限知识图实体
- "locations" -仅限名胜古迹
- 组合： "web,news", "web,videos"等等。
country, search_lang -本地化选项
freshness -时间过滤器：“pd”、“pw”、“pm”、“py”

代币成本：

result_filter="web"：约3000个令牌（仅限网络结果）✅ 推荐
result_filter=""：约10000个代币（所有集群：网络+新闻+视频+讨论）

提示： 使用专用工具(search_news, search_videos, search_images)为了获得更好的性能。

search_web_extra_snippets_for_ai

增强的网络搜索，每个结果最多可添加5个摘录（上下文增加6倍）。

要求： AI计划数据

搜索图片

搜索带有缩略图和元数据的图像。

退货： 图像URL、缩略图、源信息、尺寸

搜索_视频

搜索包含持续时间、观看次数和发布者信息的视频。

退货： 视频URL、缩略图、持续时间、视图、创建者、发布者

搜索_新闻

搜索带有突发新闻标志的新闻文章。

退货： 新闻文章、年龄、突发新闻指标、缩略图

建议

获取查询自动完成建议。

要求： 自动建议计划（可选）

拼写检查

检查并更正查询拼写。

要求： 拼写检查计划（可选）

健康终点

GET/健康

活体探针 -快速检查服务是否有效。

curl http://localhost:8081/health

答复：

{
  "status": "alive",
  "service": "Argus",
  "version": "1.0.1"
}

使用案例： 基本监控、容器重启决策

获取/准备就绪

准备就绪探针 -检查服务是否已准备好接受请求。

curl http://localhost:8081/ready

答复：

{
  "status": "ready",
  "service": "Argus",
  "version": "1.0.1",
  "capabilities": {
    "search_web": true,
    "search_web_extra_snippets_for_ai": true,
    "search_images": true,
    "search_videos": true,
    "search_news": true,
    "suggest": true,
    "spellcheck": true
  },
  "usage": {
    "data_for_search": {
      "used": 141,
      "limit": 2000,
      "remaining": 1859,
      "percentage": 7.0
    },
    "data_for_ai": {
      /* ... */
    },
    "spellcheck": {
      /* ... */
    },
    "autosuggest": {
      /* ... */
    }
  }
}

注：只有当您在中提供有效的搜索API键时，才会计算使用情况统计信息 .env没有它，你会看到的 0/2000 对于所有配额，但MCP工具仍将使用来自的密钥正常工作 .mcp.json.

使用案例： 部署验证、负载均衡器健康检查、详细监控✅ 推荐

项目结构

Argus/
├── src/
│   ├── __init__.py           # Version management (importlib.metadata)
│   ├── server.py             # MCP server and tool implementations
│   ├── config/
│   │   └── settings.py       # Configuration (pydantic-settings)
│   ├── services/
│   │   ├── brave_service.py  # Brave Search API client
│   │   └── usage_tracker.py  # API usage tracking
│   └── utils/
│       └── response_formatter.py  # Response formatting
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Container orchestration
├── pyproject.toml            # Package metadata and dependencies
├── .env.example              # Environment variables template
├── .mcp.json.example         # MCP client configuration template
└── README.md                 # This file

API关键体系结构

Argus使用双密钥架构实现最佳安全性和功能性：

启动密钥（.env）

目的： 在启动日志中显示准确的API使用情况
范围： 仅容器启动
可选： 工具在没有此键的情况下工作（如果缺少，则显示0/2000）
地点： X_BRAVE_API_KEY_SEARCH 在 .env

运行时密钥（.mcp.json）

目的： 来自MCP工具的实际API调用
范围： 通过HTTP标头的每个请求
必修的： X-Brave-API-Key-Search （最小值）
地点： .mcp.json 页眉部分

为什么分开？

Docker容器启动之前任何HTTP请求到达
启动使用检查需要密钥（否 .mcp.json 标题尚未可用）
运行时工具使用来自的每个请求密钥 .mcp.json 标头
密钥从不存储在容器中（无状态设计）

API计划和限制

计划	免费等级	工具
搜索数据	2000需求/月，1需求/秒	`search_web`, `search_images`, `search_videos`, `search_news`
AI数据	2000需求/月，1需求/秒	`search_web_extra_snippets_for_ai`
自动建议	5000需求/月，5需求/秒	`suggest`
检查拼写	5000需求/月，5需求/秒	`spellcheck`

获取API密钥-请参阅安装指南¹

常见问题解答

Why not official Brave Search MCP?

因为它不符合我的需要。

我只想依靠免费计划和官方计划 Brave Search MCP服务器支持所有计划。
官方勇敢搜索提供精心策划和剪裁的API回复。已经过滤掉了。我更喜欢API的完整JSON响应。Claude Code足够聪明，能够理解它，事实上，他喜欢它😊

No NPX?

不。

我根本不懂Node.js，因此我不使用我不懂的语言进行开发。另外，MCP Docker容器可以很好地了解您的工具是如何工作的。

Why do I need to provide a credit card for free plans?

Brave要求对所有API订阅进行信用卡验证，包括免费层。这是防止滥用的标准做法。免费等级配额（2000-5000个请求/月）对于典型使用来说足够慷慨，因此除非超过这些限制，否则您不应该收取费用。

Can I use the same API key for multiple tools?

不需要。每个Brave Search API订阅（搜索数据、人工智能数据、拼写检查、自动提示）都需要自己的API密钥。但是，您只需要“搜索数据”键即可使Argus工作，其他键是可选的，可以启用其他功能。

Why are usage stats showing 0/2000 in startup logs?

当您没有在中提供有效的搜索API密钥时，会发生这种情况 .env启动键是可选的，仅用于在日志中显示准确的配额信息。使用以下密钥，您的MCP工具仍将正常工作 .mcp.json.

What "🧠 AI-Saving Policy" log line means?

Argus有两个主要工具，您可能会使用它们：

search_web
search_web_extra_snippets_for_ai

这些工具主要用于在网络上搜索普通网站。他们当然可以搜索图像、视频、新闻，但你需要明确告诉克劳德使用这些工具。例如：

Search for an image of sad puppy dog using search_web_extra_snippets_for_ai

在这种情况下，你已经告诉克劳德使用 search_web_extra_snippets_for_ai 工具，你已经烧毁了来自的请求 Data for AI 游泳池。

然而，通常你会告诉克劳德：

Search for an image of sad puppy dog

在这种情况下，Claude将使用一个名为 search_images 因为它有一个适当的工具描述，这个工具是专门为搜索图像而优化的。但是！但它会烧掉哪种类型的请求？这就是问题所在。这两个计划（搜索数据和人工智能数据）都可以搜索图像。但你可能想为人工智能请求保存这些宝贵的数据，对吧？

这就是为什么引入了人工智能储蓄政策。其工作原理如下：

AI还剩下50%吗？
- 保存AI并使用搜索池
搜索剩余≥10%？
- 继续使用搜索池并保存AI
搜索剩余<10%？
- 搜索量正变得危险地低。留着吧 search_web 并使用AI池 search_images

AI保存策略决策树：

┌─────────────────────────────────────────────────────────────────┐
│                    AI-Saving Policy Logic                       │
└─────────────────────────────────────────────────────────────────┘

                    ┌─────────────────┐
                    │ search_images   │
                    │    called       │
                    └────────┬────────┘
                             │
                             ▼
                ┌────────────────────────┐
                │   AI remaining > 50%?  │
                └────────┬───────────────┘
                         │
            ┌────────────┴────────────┐
            │ YES                     │ NO
            ▼                         ▼
     ┌─────────────┐      ┌───────────────────────┐
     │ Use SEARCH  │      │ Search remaining ≥10%?│
     │  (save AI)  │      └──────────┬────────────┘
     └─────────────┘                 │
                          ┌──────────┴──────────┐
                          │ YES                 │ NO
                          ▼                     ▼
                   ┌─────────────┐      ┌─────────────┐
                   │ Use SEARCH  │      │   Use AI    │
                   │  (save AI)  │      │ (Search low)│
                   └─────────────┘      └─────────────┘

您会注意到这样的日志：

INFO - 🖼️  search_images called: query='sad puppy dog', count=1
INFO - 🧠 AI-Saving Policy: AI has 92.8% remaining (>50%) → Using Search to save AI
INFO - 🔑 Using Data For Search key
INFO - 🖼️  Image search: query='sad puppy dog', count=1, country=US
INFO - HTTP Request: GET https://api.search.brave.com/res/v1/images/search?q=sad+puppy+dog&count=1&country=US&search_lang=en&safesearch=strict&spellcheck=true⁠ "HTTP/1.1 200 OK"
INFO - ✅ Image search successful: 1 images returned
INFO - 📊 Used 1 request from Data For Search quota
INFO - 📊 Current Data For Search usage: [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]  144/2000 (  7.2%) - 1856 remaining

此image_search查询已为您保存了来自的请求 Data for AI 游泳池。

注： AI保存策略适用于：

search_images

search_videos

search_news

Does Argus work with other AI tools than Claude Desktop?

Argus是用Claude Code设计和测试的。它还没有在其他任何东西上进行测试，但它应该可以工作，因为它是MCP HTTP Streamable协议。

如果你在克劳德密码之外的任何东西上尝试过，请告诉我。我不能这样做，因为我没有足够的空闲时间进行这些测试。

What are the next plans?

引入API使用配额的硬限制。因此，当您达到2000个免费请求时，它将阻止任何进一步节省您资金的尝试。
CI/CD测试

脚注

[1] 勇敢搜索API指南

有关如何订阅免费计划和生成API密钥的完整设置指南和分步说明，请参阅： docs/BRAVE_SEARCH_API_GUIDE.md