Cloudflare Tavily Search MCP

一个部署在 Cloudflare Workers 上的远程网页搜索 MCP 服务。它把 Tavily 的低成本搜索包装成 web_search 工具，适合手机 AI 客户端、桌面 AI 客户端或其他支持远程 MCP 的应用。

项目默认面向个人使用：Cloudflare Workers 固定成本可以为 0，Tavily 免费方案每月提供 1,000 credits，基础搜索每次消耗 1 credit。

特性

• 使用当前 MCP TypeScript SDK v2 和 Streamable HTTP

• 自动兼容 SDK 提供的 2025-era stateless 客户端

• Tavily 搜索深度强制为 basic，避免意外使用双倍额度

• Bearer Token 鉴权，Tavily API Key 不会暴露给手机客户端

• 严格 Origin 校验和 MCP CORS 响应头

• Cloudflare Cache API 缓存重复查询

• 可选 Workers KV 月度搜索上限

• Tavily 超时、密钥错误、额度限制和服务异常的安全提示

• 完整单元测试与真实 MCP 客户端集成测试

架构

手机 AI / MCP 客户端
        │ HTTPS + Bearer Token
        ▼
Cloudflare Worker /mcp
        ├─ Origin 与鉴权
        ├─ Cache API
        ├─ 可选 KV 月度额度
        └─ Tavily Search API (basic)

服务是无状态的，不使用 Durable Objects。每个 MCP HTTP 请求创建一个临时 server 实例，因此可以直接在 Workers 上横向扩展。

环境要求

• Node.js 22 或更高版本

• npm

• Cloudflare 免费账号

• Tavily API Key：Tavily 控制台

本地运行

cd ~/Desktop/cloudflare-tavily-search-mcp
npm install
cp .dev.vars.example .dev.vars

编辑 .dev.vars：

TAVILY_API_KEY="tvly-your-api-key"
MCP_API_TOKEN="replace-with-a-long-random-token"

可以用下面的命令生成访问令牌：

openssl rand -hex 32

启动本地 Worker：

npm run dev

检查健康状态：

curl http://127.0.0.1:8787/health

部署到 Cloudflare

首次使用 Wrangler 时登录：

npx wrangler login

保存两个生产 secrets：

npx wrangler secret put TAVILY_API_KEY
npx wrangler secret put MCP_API_TOKEN

部署：

npm run deploy

部署完成后 MCP 地址类似：

https://tavily-search-mcp.<你的子域>.workers.dev/mcp

手机 AI 客户端配置

客户端需要支持 MCP Streamable HTTP，并且能够设置请求头。

通用配置示例：

{
  "url": "https://tavily-search-mcp.example.workers.dev/mcp",
  "headers": {
    "Authorization": "Bearer 你设置的 MCP_API_TOKEN"
  }
}

如果客户端只支持旧版 HTTP+SSE /sse，当前项目不会伪装成兼容：该端点会返回 HTTP 410，并提示改用 /mcp。这类客户端需要升级，或额外增加基于 Durable Objects 的旧版适配层。

MCP 工具

web_search

参数：

服务器固定发送：

{
  "search_depth": "basic",
  "include_answer": false,
  "include_raw_content": false,
  "include_images": false
}

这样每次缓存未命中的正常搜索只消耗 1 Tavily credit。

配置项

生产环境普通变量可以直接修改 wrangler.jsonc。密钥不要写进该文件或提交到 Git。

浏览器客户端的 Origin

原生手机应用和服务端 MCP 客户端通常不发送 Origin，默认即可使用。浏览器或 WebView 客户端发送 Origin 时，必须精确加入：

"ALLOWED_ORIGINS": "https://your-client.example,https://another.example"

只有明确知道风险时才配置 *。

可选：启用 KV 月度额度保护

没有 USAGE_KV 绑定时，服务仍能正常搜索，但 MAX_MONTHLY_SEARCHES 不会在 Worker 内执行。Tavily 免费账户通常会在免费额度耗尽后停止请求；如果启用了按量付费，建议同时启用 KV。

创建命名空间：

npx wrangler kv namespace create USAGE_KV

把返回的 ID 添加到 wrangler.jsonc：

"kv_namespaces": [
  {
    "binding": "USAGE_KV",
    "id": "你的 KV namespace ID"
  }
]

也可以参考 wrangler.kv.example.jsonc。默认上限是每月 900 次缓存未命中的请求，给 Tavily 免费额度留出余量。重复搜索命中缓存时不消耗本地月度额度。

KV 的读后写不是强事务计数；对个人单令牌使用足够可靠，但不适合作为多人高并发的精确计费系统。

验证与测试

npm run typecheck
npm test
npm run deploy:dry

使用官方 MCP Inspector 手动测试：

npx @modelcontextprotocol/inspector

在 Inspector 中填写 /mcp URL，并添加 Authorization: Bearer ... 请求头。

HTTP 端点

常见问题

• 401 unauthorized：客户端 Bearer Token 与 MCP_API_TOKEN 不一致。

• 403 origin_not_allowed：把客户端的完整 Origin 加入 ALLOWED_ORIGINS。

• 410 legacy_sse_not_supported：客户端使用了旧 /sse 协议，应选择 Streamable HTTP。

• Tavily 401：重新设置 TAVILY_API_KEY secret。

• Tavily 429：免费额度已用完或请求过快，等待额度重置。

• Worker 503 misconfigured：至少有一个必填 secret 没有配置。

• 中国大陆网络不稳定：可以为 Worker 绑定自定义域名，或改为部署到可稳定访问的香港服务器。

安全说明

• 不要把 Tavily Key 直接填进手机客户端。

• 为 MCP_API_TOKEN 使用至少 32 字节随机值。

• 不要公开分享 Worker URL 和访问令牌。

• 如果令牌泄露，运行 npx wrangler secret put MCP_API_TOKEN 立即轮换。

• 项目只提供搜索，不包含任意 URL 抓取工具，因此避免了常见 SSRF 风险。

项目结构

src/
  index.ts       Worker 路由、鉴权和 MCP HTTP 入口
  server.ts      web_search MCP 工具
  tavily.ts      Tavily API 客户端
  cache.ts       Cache API 封装
  quota.ts       可选 KV 月度上限
  config.ts      环境配置解析
  security.ts    Bearer、Origin 与 CORS
tests/           单元测试和 MCP 集成测试
docs/plans/      设计与实施计划

License

MIT