Tavily MCP 服务器

一个使用 Tavily API 提供基于 AI 的搜索功能的模型上下文协议 (MCP) 服务器。此服务器使 AI 助手能够执行全面的网络搜索并检索相关且最新的信息。

特性

• 基于 AI 的搜索功能
• 支持基础和高级搜索深度
• 丰富的搜索结果，包括标题、URL 和内容片段
• 搜索结果的 AI 生成摘要
• 结果评分和响应时间跟踪
• 全面的搜索历史存储与缓存
• 灵活的数据访问 MCP 资源

先决条件

• Node.js（v16 或更高版本）
• npm（Node 包管理器）
• Tavily API 密钥（在 Tavily 网站 获取）
• 一个 MCP 客户端（例如 Cline、Claude Desktop 或您自己的实现）

安装

1. 克隆仓库：

git clone https://github.com/it-beard/tavily-server.git
cd tavily-mcp-server

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

配置

此服务器可以与任何 MCP 客户端一起使用。以下是流行客户端的配置说明：

Cline 配置

如果您使用的是 Cline（Claude 的 VSCode 扩展），请创建或修改 MCP 设置文件：

• macOS: ~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev\settings\cline_mcp_settings.json

添加以下配置（用自己的路径和 API 密钥替换）：

{
  "mcpServers": {
    "tavily": {
      "command": "node",
      "args": ["/path/to/tavily-server/build/index.js"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop 配置

如果您使用的是 Claude Desktop 应用程序，请修改配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

使用与上面显示相同的配置格式。

其他 MCP 客户端

对于其他 MCP 客户端，请查阅其文档以获取正确的配置文件位置和格式。服务器配置应包括：

1. 运行服务器的命令（通常是 node）
2. 编译后的服务器文件路径
3. 环境变量，包括 Tavily API 密钥

使用

工具

服务器提供了一个名为 search 的工具，具有以下参数：

必需参数

• query (字符串): 要执行的搜索查询

可选参数

• search_depth (字符串): "basic"（更快）或 "advanced"（更全面）

示例用法

// Example using the MCP SDK
const result = await mcpClient.callTool("tavily", "search", {
  query: "latest developments in artificial intelligence",
  search_depth: "basic"
});

资源

服务器提供了静态和动态资源，以便灵活地访问数据：

静态资源

• tavily://last-search/result: 返回最近一次搜索查询的结果
  • 持久化到数据目录中的磁盘
  • 在服务器重启后仍然存在
  • 如果没有进行过搜索，则返回 '尚未执行任何搜索' 错误

动态资源（资源模板）

• tavily://search/{query}: 访问任何查询的搜索结果
  • 将 {query} 替换为您的 URL 编码搜索词
  • 示例：tavily://search/artificial%20intelligence
  • 如果之前已经进行过该查询，则返回缓存的结果
  • 如果查询以前未被搜索过，则执行并存储新的搜索
  • 返回与搜索工具相同的格式，但通过资源接口

MCP 中的资源提供了与工具相比访问数据的另一种方式：

• 工具用于执行操作（如执行新搜索）
• 资源用于访问数据（如检索现有搜索结果）
• 资源 URI 可以被存储并在以后访问
• 资源支持静态（固定）和动态（模板化）访问模式

响应格式

interface SearchResponse {
  query: string;
  answer: string;
  results: Array<{
    title: string;
    url: string;
    content: string;
    score: number;
  }>;
  response_time: number;
}

持久化存储

服务器实现了对搜索结果的全面持久化存储：

存储位置

• 数据存储在 data 目录中
• data/searches.json 包含所有历史搜索结果
• 数据在服务器重启之间保持不变
• 服务器启动时自动初始化存储

存储特性

• 存储完整的搜索历史
• 缓存所有搜索结果以便快速检索
• 自动保存新的搜索结果
• 基于磁盘的持久化
• JSON 格式便于调试
• 存储操作的错误处理
• 自动创建目录

缓存行为

• 所有搜索结果都会自动缓存
• 对相同查询的后续请求返回缓存的结果
• 缓存提高了响应时间和减少了 API 调用
• 缓存在服务器重启之间保持不变
• 跟踪最后的搜索以实现快速访问

开发

项目结构

tavily-server/
├── src/
│   └── index.ts    # Main server implementation
├── data/           # Persistent storage directory
│   └── searches.json  # Search history and cache storage
├── build/          # Compiled JavaScript files
├── package.json    # Project dependencies and scripts
└── tsconfig.json   # TypeScript configuration

可用脚本

• npm run build: 编译 TypeScript 并使输出可执行
• npm run start: 启动 MCP 服务器（构建后）
• npm run dev: 以开发模式运行服务器

错误处理

服务器为常见问题提供了详细的错误信息：

• 无效的 API 密钥
• 网络错误
• 无效的搜索参数
• API 速率限制
• 资源未找到
• 无效的资源 URI
• 存储读/写错误

贡献

1. 分叉仓库
2. 创建你的功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求

许可证

该项目根据 MIT 许可证许可 - 详情请参阅 LICENSE 文件。

致谢

• Model Context Protocol (MCP) 提供了服务器框架
• Tavily API 提供了搜索功能