Klavis Brave Search MCP Server为 AI Agent 接入 Web、新闻、图片与视频搜索的完整实战指南【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文以 Klavis 开源仓库中的mcp_servers/brave_search模块为主线基于其官方 README 与配套源码讲解 Brave Search MCP Server 的能力边界、两种部署方式托管服务与 Docker 自托管、四个搜索工具的完整参数规格以及底层的双传输协议与 API Key 解析链路帮助你在 30 秒内把 Brave 搜索能力接入自己的 AI Agent并能读懂服务端源码以排查生产问题。一、这个模块是什么mcp_servers/brave_search/README.md给出的定位是一个基于 Model Context ProtocolMCP的 Brave Search 集成服务器支持 Web 搜索、新闻搜索、图片搜索和视频搜索四类能力底层调用 Brave Search API。在 Klavis 的 MCP Server 体系中可参考 MCP Server 构建指南 对 MCP 客户端-服务器架构的说明MCP Server 充当 LLM 与外部系统之间的桥梁AI 客户端如 Claude Desktop、Cursor、VS Code发送请求MCP Server 执行具体工具并返回结果。Brave Search 模块即是以 Python 实现的一个典型只读搜索型MCP Server。从源码结构看模块非常精简server.py服务器入口定义工具注册表、请求路由与 HTTP 传输层tools/search.py四个搜索函数的实际实现HTTP 调用 Brave API;tools/base.pyAPI Key 的上下文解析逻辑Dockerfile自托管镜像定义requirements.txt唯一运行时依赖mcp1.11.0Python 3.12-slim 基础镜像。二、部署方式一Klavis 托管服务生产推荐README 首先推荐托管方式——无需任何搭建即刻获得 Brave Search 能力。核心步骤安装 SDKpip install klavis # 或 npm install klavis创建服务器实例from klavis import Klavis klavis Klavis(api_keyyour-free-key) server klavis.mcp_server.create_server_instance(BRAVE_SEARCH, user123)这里的user123是 README 中给出的示例user_id表示你访问的是哪个用户的账户与数据。仓库文档页 docs/mcp-server/brave_search.mdx 补充了更完整的托管接入流程Strata 模式包括 TypeScript 与 cURL 等价写法以及认证步骤——创建 Strata 服务器后需通过set_strata_auth传入{api_key: YOUR_BRAVE_SEARCH_API_KEY}完成 Brave 密钥绑定之后即可把返回的 MCP 端点 URL 配置到任意 MCP 兼容客户端。README 中的快速示例是这一流程的简化形式。三、部署方式二Docker 自托管README 给出的自托管命令# 拉取最新镜像 docker pull ghcr.io/klavis-ai/brave-search-mcp-server:latest # 运行 Brave Search MCP Server docker run -p 5000:5000 -e API_KEY$API_KEY \ ghcr.io/klavis-ai/brave-search-mcp-server:latest结合 Dockerfile 可以确认几个关键事实基础镜像为python:3.12-slim额外安装gcc以支持部分 Python 依赖编译构建时先拷贝requirements.txt安装依赖利用层缓存再拷贝server.py与tools/目录EXPOSE 5000声明默认端口 5000CMD [python, server.py]直接运行入口脚本环境变量API_KEY即 Brave Search API 密钥服务器会优先从该环境变量读取详见第六节鉴权链路。Brave API Key 需从 Brave Search API 控制台申请README 指向 api.search.brave.com 的 Dashboard 页面。若需从源码运行等价于 Dockerfile 的行为进入mcp_servers/brave_search/安装requirements.txt中的依赖后执行python server.py支持--port、--log-level、--json-response三个命令行参数见 server.py 中的 click 定义。四、可用工具与完整参数规格README 列出五类能力Web 搜索含排序与摘要、新闻搜索、图片搜索含元数据与来源信息、视频搜索以及搜索过滤器即各工具支持的本地化/过滤参数。从源码看前四项对应四个注册的 MCP 工具第五项是参数层面的能力而非独立工具。server.py中list_tools()注册表给出了每个工具的权威参数定义含默认值与上限以下表格即整理自该注册表工具名必填参数可选参数count 默认/上限特有说明brave_web_searchquery≤400 字符、≤50 词count,offset,country,search_lang,safesearch(off/moderate/strict)5 / 20综合 Web 搜索返回排序结果与摘要brave_image_searchquerycount,offset,search_lang,country,safesearch(off/strict)5 / 200图片搜索safesearch仅支持 off/strictbrave_news_searchquerycount,offset,country,search_lang,safesearch,freshness5 / 50支持新鲜度过滤pd(24h)、pw(7d)、pm(31d)、py(一年)或自定义YYYY-MM-DDtoYYYY-MM-DDbrave_video_searchquerycount,offset,country,search_lang,safesearch,freshness5 / 50视频搜索freshness按发现日期过滤取值同新闻参数细节要点query是唯一必填项所有工具一致count默认 5offset为零基分页偏移量country为两位国家码如USsearch_lang为语言码如en用于结果本地化四个工具的注解均为category: BRAVE_SEARCH且readOnlyHint: True明确声明这是纯读取型工具不会产生任何副作用——这对 Agent 编排中的权限判定很重要。五、请求如何被处理从 MCP 调用到 Brave APIserver.py 中call_tool()的调度逻辑是名称匹配 异常兜底按工具名分发到 tools/search.py 中对应的异步函数结果以json.dumps(result, indent2)序列化为TextContent返回任何异常都会记录日志并返回Error: ...文本而非抛出保证 MCP 会话不被中断。四个搜索函数的实现模式一致以brave_web_search为例端点分别为https://api.search.brave.com/res/v1/web/search、/images/search、/news/search、/videos/search四个函数中的url变量鉴权头为x-subscription-token取自get_brave_client()请求头另含Accept: application/json与Accept-Encoding: gzip查询参数以q关键词与count为基础其余可选参数country、search_lang、offset、safesearch、freshness采用非 None 才附加的策略避免向 Brave API 传空值使用httpx.AsyncClient异步发起 GETWeb 搜索额外调用response.raise_for_status()显式检查 HTTP 状态码失败时返回{error: Could not complete Brave search for query: ...}结构化错误体。从 tools/base.py 可以看到所有请求共用同一个 token 解析入口get_brave_client()其内部调用get_auth_token()。六、API Key 从哪来三级解析链路这是该模块最有工程价值的细节。tools/base.py定义了一个ContextVarauth_token_context用于按请求隔离 API Key而server.py的extract_api_key()与两处传输处理器共同构成了完整链路环境变量API_KEY最高优先级extract_api_key()首先读取os.getenv(API_KEY)——这正是 README 中 Docker 命令-e API_KEY$API_KEY传入的值适合单密钥场景如个人自托管请求头x-auth-data多租户场景若无环境变量则从请求头中取x-auth-data该值是 Base64 编码的 JSON解码后读取其中的token或api_key字段。server.py分别处理了 SSE 请求对象与 StreamableHTTP scope 字典两种形态并在 JSON 解析失败时降级为空并记录 warning环境变量BRAVE_SEARCH_API_KEY最终兜底get_auth_token()在上下文未设置LookupError或上下文值为空时回退到BRAVE_SEARCH_API_KEY环境变量两者皆无则抛出RuntimeError由get_brave_client()捕获并返回None最终使搜索函数返回 Missing Brave subscription token 错误。每一级都有对应的日志与降级路径且server.py的 SSE/StreamableHTTP 两个 handler 都在请求开始时auth_token_context.set(api_key)、结束时reset保证并发请求间密钥互不串号。七、双传输协议与客户端接入server.py用 Starlette 同时挂载了两种 MCP 传输启动日志会打印 dual transportsSSE 端点GET /sse建立连接POST /messages/消息通道基于SseServerTransportStreamableHTTP 端点Mount(/mcp, ...)基于StreamableHTTPSessionManager配置为statelessTrue、无事件存储可通过--json-response开关把响应切换为 JSON 而非 SSE 流。因此客户端配置指向http://localhost:5000/mcp/StreamableHTTP或http://localhost:5000/sseSSE均可。仓库文档页 docs/mcp-server/brave_search.mdx 给出的客户端配置示例{ mcpServers: { brave_search: { url: http://localhost:5000/mcp/ } } }端口方面server.py从环境变量BRAVE_SEARCH_MCP_SERVER_PORT读取默认值缺省 5000--port参数可覆盖uvicorn监听0.0.0.0这与 Dockerfile 的EXPOSE 5000及 README 的-p 5000:5000完全对应。八、小结与延伸阅读模块实现服务器入口与工具注册表、搜索函数实现、密钥上下文解析、工具包导出部署资产Dockerfile、依赖清单、模块 README产品文档Brave Search 接入指南含托管/Strata/自托管三种 Tab贡献与测试规范MCP Server 构建指南含用自然语言端到端验证工具调用并留存证据的要求、CONTRIBUTING.md许可模块随仓库采用 Apache 2.0见 LICENSE。该模块麻雀虽小五脏俱全四个只读搜索工具、参数上限与枚举约束、双传输协议、按请求隔离的多租户密钥链路构成了一份可直接参照的API 代理型 MCP Server参考实现。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考