news 2026/5/6 9:19:42

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

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
基于Cloudflare Workers构建AI助手聚合搜索服务与MCP集成指南

1. 项目概述：一个基于Cloudflare Workers的聚合搜索服务

最近在折腾AI助手（比如Claude Code、OpenClaw）时，发现一个痛点：想让它们联网搜索，要么得折腾复杂的API，要么得付费订阅。正好看到Yrobot大佬开源的这个cloudflare-search项目，眼前一亮。它本质上是一个部署在Cloudflare Workers上的无服务器聚合搜索API，能把Google、Brave、DuckDuckGo等多个搜索引擎的结果并行抓取、合并返回。最吸引我的是，它原生支持MCP（Model Context Protocol），这意味着我只需要部署一次，就能让我的AI助手们瞬间获得实时联网搜索的能力，而且完全免费（Cloudflare Workers每天有10万次免费请求额度）。这简直就是为个人开发者和AI爱好者量身定做的“搜索引擎中间件”。我自己部署、调试了一遍，把过程中的关键步骤、配置细节和踩过的坑都梳理了出来，如果你也想低成本、高效率地给AI装上一个“外挂大脑”，这篇实操指南应该能帮到你。

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

2.1 为什么选择Cloudflare Workers？

这个项目的基石是Cloudflare Workers，一个全球分布式的无服务器计算平台。选择它有几个无法拒绝的理由：

  1. 免费额度足够个人使用：每天10万次请求，对于个人或小团队来说，支撑AI助手偶尔的搜索查询绰绰有余，真正实现了零成本运行。
  2. 全球边缘网络：代码部署在Cloudflare全球数百个节点上，无论用户在哪里，请求都能被最近的节点处理，延迟极低，这对于搜索这种对响应速度敏感的服务至关重要。
  3. 无需运维：你不用操心服务器配置、系统更新、负载均衡这些琐事，只需要专注于业务逻辑（也就是搜索聚合的代码）。
  4. 原生支持Web标准：Workers环境基于Service Workers API，可以直接使用fetch、crypto等现代Web API，开发搜索代理这种HTTP服务非常顺手。

项目的核心逻辑，就是在一个Worker脚本里，接收前端的搜索请求，然后同时向配置好的多个搜索引擎API发起并行请求，最后将各家的结果去重、排序、合并，以一个统一的JSON格式返回给客户端。这种“扇出-聚合”的模式，是提高并发性能的经典设计。

2.2 聚合搜索与MCP集成的价值

单纯做一个搜索聚合API，价值有限。这个项目真正的“杀手锏”在于对MCP（Model Context Protocol）的原生支持。MCP是Anthropic提出的一种协议，旨在让AI助手能够安全、标准化地使用外部工具和数据源。

传统AI联网搜索的痛点：通常需要你手动编写或寻找一个兼容的搜索工具插件，配置复杂的API密钥，还要处理不同AI客户端（如Claude Desktop, Cursor, Windsurf）的差异，过程繁琐。

本项目的解决方案：cloudflare-search将自己包装成一个标准的MCP服务器。一旦部署好，你只需要在AI客户端的配置文件中添加几行配置，指向你的Worker地址和令牌。之后，AI助手在对话中就能直接调用这个搜索工具，就像调用一个内置函数一样简单。它把复杂的后端部署、API聚合、认证等问题都封装了起来，对用户和AI来说，暴露的只是一个简单的“搜索”功能接口。这种设计极大地降低了AI获取实时信息能力的门槛。

3. 从零开始的完整部署与配置指南

3.1 环境准备与项目获取

部署前，你需要准备以下几样东西：

  1. 一个Cloudflare账户：如果没有，去官网免费注册一个。
  2. Node.js环境（可选）：如果你打算使用Wrangler CLI命令行工具进行部署，需要在本地安装Node.js。如果使用一键部署或Dashboard，则不需要。
  3. 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（可视化操作）

  1. 登录 Cloudflare Dashboard 。
  2. 侧边栏进入Workers & Pages。
  3. 点击Create application>Create Worker。
  4. 你会看到一个在线编辑器。不要在这里写代码，而是点击右上角的Upload按钮，将你本地cloudflare-search文件夹下的所有文件（worker.js,envs.js,utils/文件夹等）打包成ZIP上传，或者直接拖拽进去。
  5. 点击Save and Deploy。

实操心得：对于第一次接触Cloudflare Workers的朋友，我强烈建议从方式一（一键部署）开始，最快看到效果。等熟悉了，再尝试用CLI进行更高级的管理。方式三（Dashboard上传）适合做一次性部署或紧急修改。

部署成功后，你会获得一个类似https://your-worker-name.your-subdomain.workers.dev的默认域名。请注意：这个*.workers.dev的域名在某些网络环境下可能无法直接访问。所以，绑定自定义域名几乎是必须的步骤，我们后面会讲。

3.3 关键环境变量配置详解

环境变量是配置这个Worker行为的核心。你需要根据想使用的搜索引擎来设置。所有配置都可以在Cloudflare Dashboard中该Worker的Settings>Variables页面完成，或者如果你用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域名可能被干扰。绑定自己的域名是最佳实践：

  1. 在Cloudflare Dashboard中，进入你的Worker详情页。
  2. 点击Triggers标签页。
  3. 在Custom Domains区域，点击Add Custom Domain。
  4. 输入你已经添加到Cloudflare并代理（橙色云朵点亮）的域名或子域名，例如search.yourdomain.com。
  5. 按照提示完成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=什么是Cloudflare+Workers" # 指定使用Brave和DuckDuckGo引擎 curl "https://search.yourdomain.com/search?q=AI+news&engines=brave,duckduckgo" # 携带令牌进行认证（如果配置了TOKEN） curl "https://search.yourdomain.com/search?q=test&token=your_secret_token_here"

GET请求非常直观，参数都放在URL里，方便在浏览器、命令行或任何能发起HTTP请求的地方使用。

POST请求示例：

curl -X POST "https://search.yourdomain.com/search" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "q=什么是Cloudflare+Workers" \ -d "engines=google,brave" \ -d "token=your_secret_token_here"

POST请求将参数放在请求体中，更适合从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搜索

  1. 找到配置文件位置：

    • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows:%APPDATA%\Claude\claude_desktop_config.json
    • Linux:~/.config/Claude/claude_desktop_config.json如果文件或目录不存在，就手动创建它。

  2. 编辑配置文件：用文本编辑器打开（或创建）上述文件，填入以下内容。请务必将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服务器进程，并通过环境变量连接到你的后端。

  1. 重启Claude Desktop：保存配置文件后，完全退出并重新启动Claude Desktop应用程序。

  2. 验证连接：重启后，在Claude的聊天框中，你应该能看到一个新增的“搜索”工具图标，或者当你输入相关内容时，Claude会主动建议使用搜索工具。你也可以在Claude的输入框里尝试输入/mcp命令来查看已连接的MCP服务器列表。

5.2 为Cursor（或OpenClaw）配置MCP搜索

Cursor编辑器内置了OpenClaw，配置方式类似，但配置文件路径不同。

  1. 找到或创建配置文件：

    • OpenClaw的全局配置文件通常位于~/.openclaw/openclaw.json。

  2. 编辑配置文件：内容与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" } } } }

  1. 重启Cursor/OpenClaw：保存配置，重启你的编辑器或IDE。

  2. 验证与使用：重启后，在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 安全加固与防滥用指南

  1. 强制使用令牌（TOKEN）：这绝对是最重要的一步。一个没有令牌保护的公开搜索端点，很快就会被爬虫扫到并滥用，导致你的Google API配额瞬间耗尽，甚至可能因为异常请求导致Cloudflare账户被审查。
  2. 使用强令牌：令牌不要用简单的单词或数字。使用密码生成器或命令行（如openssl rand -base64 32）生成一个足够长且随机的字符串。
  3. 考虑速率限制：Cloudflare Workers本身可以在代码层面实现简单的速率限制，例如基于请求IP或令牌，在短时间内限制请求次数。原项目未内置此功能，但对于公开服务，这是一个值得添加的防护层。你可以利用Worker的KV命名空间来存储和检查请求计数。
  4. 监控用量：定期登录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，社区的力量通常能帮你找到答案。

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/5/6 9:13:28

Zotero插件市场：一站式插件管理平台，让学术研究效率翻倍

Zotero插件市场：一站式插件管理平台，让学术研究效率翻倍 【免费下载链接】zotero-addons Zotero Add-on Market | Zotero插件市场 | Browsing, installing, and reviewing plugins within Zotero 项目地址: https://gitcode.com/gh_mirrors/zo/zotero-…

作者头像 李华
网站建设 2026/5/6 9:07:25

从石英到氟化镁：手把手教你用OpticStudio设计宽带消色差波片

石英与氟化镁组合优化：OpticStudio宽带消色差波片设计实战 在激光加工、光谱分析和量子光学等领域，宽带消色差波片是实现精确偏振控制的核心元件。与单色波片不同，这类元件需要在连续光谱范围内保持稳定的相位延迟特性，这对材料选…

作者头像 李华
网站建设 2026/5/6 9:05:27

基于Docker与FastAPI的生成式AI应用全栈开发实战

1. 项目概述：一个面向生产环境的生成式AI应用全栈解决方案最近在折腾生成式AI应用落地的朋友，估计都绕不开一个核心痛点：从模型原型到稳定、可扩展的生产系统，中间隔着一条巨大的鸿沟。你或许能用几行代码快速调用API跑通一个Demo…

作者头像 李华
网站建设 2026/5/6 8:57:58

基于MCP的能源转型情报引擎：为AI智能体提供量化分析与自动化决策支持

1. 项目概述：一个为AI智能体赋能的能源转型情报引擎 如果你在能源投资、电网运营或者气候金融领域工作，你肯定知道获取实时、结构化、可量化的市场情报有多麻烦。传统路径无非两条：要么花几天时间手动拼接七八个不同的政府数据API&#xff0…

作者头像 李华