基于Cloudflare Workers构建AI助手聚合搜索服务与MCP集成指南

1. 项目概述一个基于Cloudflare Workers的聚合搜索服务最近在折腾AI助手比如Claude Code、OpenClaw时发现一个痛点想让它们联网搜索要么得折腾复杂的API要么得付费订阅。正好看到Yrobot大佬开源的这个cloudflare-search项目眼前一亮。它本质上是一个部署在Cloudflare Workers上的无服务器聚合搜索API能把Google、Brave、DuckDuckGo等多个搜索引擎的结果并行抓取、合并返回。最吸引我的是它原生支持MCPModel Context Protocol这意味着我只需要部署一次就能让我的AI助手们瞬间获得实时联网搜索的能力而且完全免费Cloudflare Workers每天有10万次免费请求额度。这简直就是为个人开发者和AI爱好者量身定做的“搜索引擎中间件”。我自己部署、调试了一遍把过程中的关键步骤、配置细节和踩过的坑都梳理了出来如果你也想低成本、高效率地给AI装上一个“外挂大脑”这篇实操指南应该能帮到你。2. 核心设计思路与架构解析2.1 为什么选择Cloudflare Workers这个项目的基石是Cloudflare Workers一个全球分布式的无服务器计算平台。选择它有几个无法拒绝的理由免费额度足够个人使用每天10万次请求对于个人或小团队来说支撑AI助手偶尔的搜索查询绰绰有余真正实现了零成本运行。全球边缘网络代码部署在Cloudflare全球数百个节点上无论用户在哪里请求都能被最近的节点处理延迟极低这对于搜索这种对响应速度敏感的服务至关重要。无需运维你不用操心服务器配置、系统更新、负载均衡这些琐事只需要专注于业务逻辑也就是搜索聚合的代码。原生支持Web标准Workers环境基于Service Workers API可以直接使用fetch、crypto等现代Web API开发搜索代理这种HTTP服务非常顺手。项目的核心逻辑就是在一个Worker脚本里接收前端的搜索请求然后同时向配置好的多个搜索引擎API发起并行请求最后将各家的结果去重、排序、合并以一个统一的JSON格式返回给客户端。这种“扇出-聚合”的模式是提高并发性能的经典设计。2.2 聚合搜索与MCP集成的价值单纯做一个搜索聚合API价值有限。这个项目真正的“杀手锏”在于对MCPModel Context Protocol的原生支持。MCP是Anthropic提出的一种协议旨在让AI助手能够安全、标准化地使用外部工具和数据源。传统AI联网搜索的痛点通常需要你手动编写或寻找一个兼容的搜索工具插件配置复杂的API密钥还要处理不同AI客户端如Claude Desktop, Cursor, Windsurf的差异过程繁琐。本项目的解决方案cloudflare-search将自己包装成一个标准的MCP服务器。一旦部署好你只需要在AI客户端的配置文件中添加几行配置指向你的Worker地址和令牌。之后AI助手在对话中就能直接调用这个搜索工具就像调用一个内置函数一样简单。它把复杂的后端部署、API聚合、认证等问题都封装了起来对用户和AI来说暴露的只是一个简单的“搜索”功能接口。这种设计极大地降低了AI获取实时信息能力的门槛。3. 从零开始的完整部署与配置指南3.1 环境准备与项目获取部署前你需要准备以下几样东西一个Cloudflare账户如果没有去官网免费注册一个。Node.js环境可选如果你打算使用Wrangler CLI命令行工具进行部署需要在本地安装Node.js。如果使用一键部署或Dashboard则不需要。Google Custom Search API密钥可选如果你想启用Google搜索需要去Google Cloud Console申请。这是整个配置里相对复杂的一步后面会详细讲。首先获取项目代码。最方便的方式是直接Fork或克隆原仓库git clone https://github.com/Yrobot/cloudflare-search.git cd cloudflare-search这样你就能在本地看到项目的全部文件核心是worker.js主逻辑、envs.js环境变量与引擎配置以及utils/目录下的辅助函数。3.2 三种部署方式详解与选择项目提供了三种部署方式各有优劣我逐一分析方式一一键部署最推荐给新手直接在项目README页面点击那个蓝色的“Deploy to Cloudflare Workers”按钮。这会跳转到Cloudflare的部署界面你只需要登录账号然后跟着向导一步步点下去即可。系统会自动为你创建一个新的Worker并配置好基础代码。这种方式最省心但后续如果要自定义环境变量需要去Dashboard里手动添加。方式二使用Wrangler CLI推荐给开发者Wrangler是Cloudflare官方的Workers命令行工具提供了最全面的控制能力。# 1. 全局安装Wrangler npm install -g wrangler # 2. 登录你的Cloudflare账号 wrangler login # 这会打开浏览器完成授权。 # 3. 在项目根目录初始化并部署 wrangler deploy使用CLI的优势在于你可以通过本地的wrangler.toml文件精细地管理所有配置包括环境变量、路由等并且部署、日志查看、测试都在命令行完成非常适合集成到自动化流程中。方式三使用Cloudflare Dashboard可视化操作登录 Cloudflare Dashboard 。侧边栏进入Workers Pages。点击Create applicationCreate Worker。你会看到一个在线编辑器。不要在这里写代码而是点击右上角的Upload按钮将你本地cloudflare-search文件夹下的所有文件worker.js,envs.js,utils/文件夹等打包成ZIP上传或者直接拖拽进去。点击Save and Deploy。实操心得对于第一次接触Cloudflare Workers的朋友我强烈建议从方式一一键部署开始最快看到效果。等熟悉了再尝试用CLI进行更高级的管理。方式三Dashboard上传适合做一次性部署或紧急修改。部署成功后你会获得一个类似https://your-worker-name.your-subdomain.workers.dev的默认域名。请注意这个*.workers.dev的域名在某些网络环境下可能无法直接访问。所以绑定自定义域名几乎是必须的步骤我们后面会讲。3.3 关键环境变量配置详解环境变量是配置这个Worker行为的核心。你需要根据想使用的搜索引擎来设置。所有配置都可以在Cloudflare Dashboard中该Worker的SettingsVariables页面完成或者如果你用CLI则在wrangler.toml文件的[vars]部分设置。1. 超时控制 (DEFAULT_TIMEOUT)默认值是3000单位毫秒。这意味着每个搜索引擎API请求最多等待3秒。如果某个引擎3秒内没响应它就会被标记为“无响应”不影响其他引擎的结果返回。如果你的网络环境对某些引擎比如Bing访问较慢可以适当调高比如5000。但我不建议设得过高否则一次失败的请求会拖慢整个搜索的响应速度。2. 认证令牌 (TOKEN)这是保护你服务不被滥用的关键如果你不设置TOKEN那么任何人拿到你的Worker地址都可以随意调用搜索消耗你的免费额度甚至导致IP被搜索引擎限制。设置方法在环境变量中添加TOKEN值设为一个复杂的随机字符串比如用命令生成的openssl rand -hex 16。生效后所有向该Worker发起的请求包括访问Web界面和调用API都必须在URL参数或POST表单中携带token你的令牌否则会返回401未授权错误。3. Google搜索配置 (GOOGLE_API_KEY和GOOGLE_CX)Google搜索不是免费的午餐它通过“可编程搜索引擎”API提供有限额度的服务。GOOGLE_API_KEY去 Google Cloud Console 创建一个项目启用“Custom Search API”然后创建一个API密钥。GOOGLE_CX去 Google可编程搜索引擎控制台 创建一个搜索引擎。这里有个关键点在创建时你可以选择“搜索整个网络”这样才能获得通用的网页搜索结果而不是只搜索你指定的网站。创建好后在搜索引擎的详情页就能找到你的“搜索引擎ID”这就是CX。免费额度Google Custom Search API免费层每天只有100次搜索请求超出后会产生费用。对于个人辅助使用通常够用但请留意。4. 默认搜索引擎 (DEFAULT_ENGINES)这个配置在代码文件envs.js中而不是环境变量。你可以修改const DEFAULT_ENGINES数组来决定默认启用哪些引擎。原项目默认启用了[google, brave, duckduckgo]禁用了bing因为其结果稳定性不佳。你可以按需调整比如只保留[brave, duckduckgo]来避免配置Google API的麻烦。3.4 绑定自定义域名与优化访问如前所述默认的workers.dev域名可能被干扰。绑定自己的域名是最佳实践在Cloudflare Dashboard中进入你的Worker详情页。点击Triggers标签页。在Custom Domains区域点击Add Custom Domain。输入你已经添加到Cloudflare并代理橙色云朵点亮的域名或子域名例如search.yourdomain.com。按照提示完成DNS记录的验证通常是自动的。 绑定后你就可以通过https://search.yourdomain.com来稳定访问你的搜索服务了。4. 核心功能使用与API调用实战4.1 通过Web界面快速测试部署并配置好环境变量后最简单的测试方法就是直接在你的Worker地址后面加上/访问其Web界面。例如https://search.yourdomain.com/。你会看到一个简洁的搜索框。输入关键词点击搜索页面会以JSON格式展示聚合后的结果。如果配置了TOKEN你需要在URL中带上?token你的令牌才能正常访问首页和搜索。这个Web界面非常适合用来快速验证服务是否工作正常以及各个搜索引擎的返回情况。4.2 搜索API的两种调用方式作为API服务它支持GET和POST两种请求方式返回统一的JSON格式。GET请求示例最常用# 基础搜索 curl https://search.yourdomain.com/search?q什么是CloudflareWorkers # 指定使用Brave和DuckDuckGo引擎 curl https://search.yourdomain.com/search?qAInewsenginesbrave,duckduckgo # 携带令牌进行认证如果配置了TOKEN curl https://search.yourdomain.com/search?qtesttokenyour_secret_token_hereGET请求非常直观参数都放在URL里方便在浏览器、命令行或任何能发起HTTP请求的地方使用。POST请求示例curl -X POST https://search.yourdomain.com/search \ -H Content-Type: application/x-www-form-urlencoded \ -d q什么是CloudflareWorkers \ -d enginesgoogle,brave \ -d tokenyour_secret_token_herePOST请求将参数放在请求体中更适合从Web前端表单提交或某些对URL长度有限制的场景。两种方式的响应格式完全一样。4.3 深入理解API响应结构API的响应是一个结构清晰的JSON对象理解每个字段有助于你更好地处理结果{ query: cloudflare workers, // 用户搜索的关键词 number_of_results: 8, // 聚合后的总结果数量 enabled_engines: [google, brave], // 本次查询启用的引擎列表 unresponsive_engines: [duckduckgo], // 本次查询中无响应的引擎列表重要 results: [ // 核心结果数组按相关性排序 { title: Cloudflare Workers · Cloudflare Developers docs, description: Cloudflare Workers provides a serverless execution environment that allows you to create..., url: https://developers.cloudflare.com/workers/, engine: google // 该结果来源于哪个引擎 }, { title: Cloudflare Workers - Wikipedia, description: Cloudflare Workers is a serverless platform..., url: https://en.wikipedia.org/wiki/Cloudflare_Workers, engine: brave } // ... 更多结果 ] }unresponsive_engines字段非常实用它能立刻告诉你哪个搜索引擎API这次“掉链子”了方便你排查是网络问题、配置错误还是引擎本身的服务故障。engine字段让你能区分结果的来源这对于分析不同搜索引擎的偏好或进行数据对比很有帮助。4.4 在前端项目中集成搜索有了这个统一的搜索API你可以轻松地把它集成到自己的博客、文档站或任何Web应用中。// 一个简单的异步搜索函数示例 async function performSearch(query, apiUrl, token) { const url new URL(${apiUrl}/search); url.searchParams.append(q, query); url.searchParams.append(engines, brave,duckduckgo); // 按需选择引擎 if (token) { url.searchParams.append(token, token); } try { const response await fetch(url); if (!response.ok) { throw new Error(搜索请求失败: ${response.status}); } const data await response.json(); // 处理结果 if (data.unresponsive_engines.length 0) { console.warn(以下引擎未响应: ${data.unresponsive_engines.join(, )}); } return data.results; // 返回结果列表 } catch (error) { console.error(搜索出错:, error); return []; // 返回空数组或错误信息 } } // 调用示例 const results await performSearch( JavaScript最新特性, https://search.yourdomain.com, your_token_here );这样你就拥有了一个私有的、可定制的站内或应用内搜索服务。5. 与AI助手集成MCP配置全流程这是本项目最精彩的部分。下面以Claude Desktop和Cursor集成OpenClaw为例详细讲解如何配置。5.1 为Claude Desktop配置MCP搜索找到配置文件位置macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在就手动创建它。编辑配置文件用文本编辑器打开或创建上述文件填入以下内容。请务必将CF_SEARCH_URL和CF_SEARCH_TOKEN替换成你实际部署的地址和令牌。{ mcpServers: { cloudflare-search: { command: npx, args: [-y, yrobot/cf-search-mcp], env: { CF_SEARCH_URL: https://search.yourdomain.com, // 你的Worker地址 CF_SEARCH_TOKEN: your_secret_token_here // 你的访问令牌 } } } }注意yrobot/cf-search-mcp是一个独立的NPM包它是cloudflare-search项目的MCP客户端适配器。当Claude启动时它会自动执行npx -y yrobot/cf-search-mcp这个命令来启动MCP服务器进程并通过环境变量连接到你的后端。重启Claude Desktop保存配置文件后完全退出并重新启动Claude Desktop应用程序。验证连接重启后在Claude的聊天框中你应该能看到一个新增的“搜索”工具图标或者当你输入相关内容时Claude会主动建议使用搜索工具。你也可以在Claude的输入框里尝试输入/mcp命令来查看已连接的MCP服务器列表。5.2 为Cursor或OpenClaw配置MCP搜索Cursor编辑器内置了OpenClaw配置方式类似但配置文件路径不同。找到或创建配置文件OpenClaw的全局配置文件通常位于~/.openclaw/openclaw.json。编辑配置文件内容与Claude Desktop的配置几乎完全相同。{ mcpServers: { cloudflare-search: { command: npx, args: [-y, yrobot/cf-search-mcp], env: { CF_SEARCH_URL: https://search.yourdomain.com, CF_SEARCH_TOKEN: your_secret_token_here } } } }重启Cursor/OpenClaw保存配置重启你的编辑器或IDE。验证与使用重启后在Cursor中召唤出AI助手通常是Cmd/Ctrl K当你问它需要最新信息的问题时比如“今天科技圈有什么大新闻”它应该会主动调用搜索工具并在回答中引用搜索结果。5.3 MCP集成的工作原理与排查工作原理简述AI客户端Claude, Cursor启动时会读取配置文件并执行你指定的command这里是npx -y yrobot/cf-search-mcp来启动一个本地MCP服务器进程。这个进程作为“桥梁”负责将AI客户端的工具调用请求转发到你配置的CF_SEARCH_URL即你部署的Cloudflare Search Worker然后将Worker返回的搜索结果再传回给AI客户端。常见问题排查工具未出现首先检查配置文件路径和格式是否正确JSON不能有语法错误。然后检查终端或系统日志看启动MCP服务器时是否有错误输出如网络连接失败、令牌错误等。搜索无结果或报错在AI客户端内搜索失败很可能是因为你的Worker服务本身有问题。请先直接用浏览器或curl测试你的Worker API是否能正常返回结果确保后端服务是通的。连接超时检查CF_SEARCH_URL是否正确以及你的网络是否能访问该地址。如果Worker绑定了自定义域名请确保DNS解析正确。实操心得配置MCP时最容易出错的就是配置文件路径和JSON格式。建议使用能校验JSON格式的编辑器如VSCode。另外确保你用于启动AI客户端的系统用户有权限执行npx命令。如果遇到权限问题可以尝试全局安装MCP客户端包npm install -g yrobot/cf-search-mcp然后将配置文件中的command改为cf-search-mcp。6. 高级技巧、问题排查与安全建议6.1 性能调优与引擎选择策略精简引擎列表不是所有搜索都需要调用全部引擎。在请求API时通过engines参数指定或在envs.js中修改DEFAULT_ENGINES只保留你真正需要的。例如如果主要用英文搜索brave和duckduckgo通常就足够了响应快且免费。google虽然质量高但有每日限额。合理设置超时DEFAULT_TIMEOUT不宜过长。对于国际网络3-5秒是合理范围。如果一个引擎经常超时可以考虑将其从默认列表中移除仅在需要时手动指定。关注unresponsive_engines在开发集成时记得处理这个字段。如果某个引擎频繁无响应可以给你的用户一个提示或者在后续请求中临时屏蔽它。6.2 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案访问Worker地址返回404或错误1. 部署未成功2. 路由未配置3. 自定义域名未生效1. 登录Cloudflare Dashboard检查Worker是否处于“Active”状态。2. 确保访问的路径是/或/search。3. 检查自定义域名的DNS解析状态通常需要几分钟生效。API搜索返回空结果{“results“: []}1. 所有引擎均无响应2. 搜索引擎API密钥无效或超额3. 搜索词太冷门1. 检查响应中的unresponsive_engines字段看哪些引擎挂了。2. 单独测试每个引擎的API如直接curl Brave搜索。3. 检查Google API密钥和CX是否配置正确并去Google Cloud Console查看配额用量。请求返回401 Unauthorized未提供或提供了错误的token参数确认你在环境变量中配置了TOKEN。在请求的URL或Body中确保token参数的值与配置完全一致注意大小写和特殊字符。MCP配置后AI助手无搜索工具1. 配置文件路径错误2. JSON格式错误3. MCP服务器启动失败1. 仔细核对Claude/Cursor的配置文件路径。2. 使用JSON校验工具检查配置文件。3. 在终端手动运行npx -y yrobot/cf-search-mcp查看是否有报错如环境变量缺失。搜索响应速度很慢1. 某个引擎超时默认3秒2. 网络环境不佳3. 启用了过多引擎1. 查看响应中的unresponsive_engines可能是某个引擎拖慢了整体响应。2. 尝试减少并发引擎数量。3. 考虑将服务部署在离你主要用户群更近的Cloudflare区域虽然Workers是全球边缘但初始请求可能有差异。6.3 安全加固与防滥用指南强制使用令牌TOKEN这绝对是最重要的一步。一个没有令牌保护的公开搜索端点很快就会被爬虫扫到并滥用导致你的Google API配额瞬间耗尽甚至可能因为异常请求导致Cloudflare账户被审查。使用强令牌令牌不要用简单的单词或数字。使用密码生成器或命令行如openssl rand -base64 32生成一个足够长且随机的字符串。考虑速率限制Cloudflare Workers本身可以在代码层面实现简单的速率限制例如基于请求IP或令牌在短时间内限制请求次数。原项目未内置此功能但对于公开服务这是一个值得添加的防护层。你可以利用Worker的KV命名空间来存储和检查请求计数。监控用量定期登录Cloudflare Dashboard在Workers的Metrics标签页下查看请求量、错误率和CPU时间消耗。同时关注Google Cloud Console的API配额使用情况避免产生意外费用。6.4 扩展思路与自定义开发这个项目提供了一个优秀的骨架你完全可以基于它进行二次开发添加新的搜索引擎在envs.js的ENGINES对象中仿照现有格式添加新的引擎配置实现其对应的search函数即可。你需要找到该引擎的公开API或爬取方式。结果后处理在worker.js中聚合结果后你可以增加去重根据URL或标题、自定义排序如优先某个引擎的结果、内容过滤或高亮等逻辑。缓存机制对于热门搜索词可以使用Cloudflare的Cache API甚至KV来缓存搜索结果一段时间减少对上游搜索引擎的请求并大幅提升响应速度。输出格式定制除了默认的JSON你可以修改代码使其支持RSS、Atom甚至自定义的HTML片段输出以适应不同的前端展示需求。部署并运行这个cloudflare-search项目后最直观的感受就是“自由”。你不再受限于某个特定AI产品的封闭插件生态而是拥有了一个完全由自己掌控的、可无缝接入多种AI工作流的实时信息入口。从配置Google API的小麻烦到绑定自定义域名时DNS生效的等待再到最后在Claude中看到它引用着刚刚从网上搜到的信息来回答你——整个过程就像在搭建一个属于自己的数字基础设施。这种将复杂后端封装成简单工具并通过MCP这类开放协议提供给AI使用的模式或许正是未来人机协作的常态。如果你在配置过程中遇到了其他问题不妨多看看Cloudflare Workers的官方文档和项目的GitHub Issues社区的力量通常能帮你找到答案。