🔍 我的 Tavily 搜索 MCP 代理

我创建了一个强大的由 Tavily API 驱动的模型上下文协议 (MCP) 服务器。 通过它，您可以从商业、新闻、金融和政治领域获得高质量、可靠的信息——所有这些都通过一个强大且对开发者友好的界面实现。

🌟 为什么我构建 Tavily 搜索 MCP

在当今快节奏的数字环境中，我认识到需要快速访问精确信息。 我需要一个可以与我的顺序思维 MCP 服务器配合使用的网络搜索工具。 这就是我开发 Tavily 搜索 MCP 的原因，它擅长：

⚡️ 闪电般的异步搜索响应 🛡️ 内置容错，具有自动重试功能 🎯 干净的 Markdown 格式结果 🔍 智能内容片段 🛠️ 全面的错误处理 🖼️ 可选的图像结果 📰 专业的资讯搜索

🚀 快速开始

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Tavily 搜索：

npx -y @smithery/cli install mcp-tavily-search --client claude

手动安装

以下是如何在几分钟内启动并运行我的项目：

# 1. 创建环境
uv venv && .venv\Scripts\activate     # Windows
# OR
uv venv && source .venv/bin/activate  # Unix/MacOS

# 2. 安装依赖
uv pip install -e .

# 3. 设置配置
echo TAVILY_API_KEY=your-key-here > .env

# 4. 启动服务器
cd mcp_tavily_search && uv run server.py

💡 核心功能

⚡️ 性能与可靠性

• 我已经实现了异步请求处理
• 内置错误处理和自动重试
• 可配置的请求超时
• 完善的日志记录系统

🎯 搜索配置

• 我已经使搜索深度可配置（基本/高级）
• 可调整的结果限制（1-20 个结果）
• 干净的 Markdown 格式输出
• 带有源 URL 的片段预览
• 可选的图像结果
• 专业的资讯搜索主题

🛡️ 错误处理

• API 身份验证验证
• 速率限制检测
• 网络错误恢复
• 请求超时管理

🛠️ 开发者集成

前提条件

• Python 3.11 或更高版本
• UV 包管理器 (安装指南)
• Tavily API 密钥 (在此处获取)

Claude Desktop 设置

我使用以下配置优化了 Claude Desktop 体验：

{
  "mcpServers": {
    "tavily-search": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-tavily-search/mcp_tavily_search",
        "run",
        "server.py"
      ],
      "env": {
        "TAVILY_API_KEY": "YOUR-API-KEY"
      }
    }
  }
}

📁 配置路径：

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Unix/MacOS: ~/.config/Claude/claude_desktop_config.json

项目架构

我设计了一个干净、模块化的结构，使开发变得轻而易举：

mcp-tavily-search/
├── mcp_tavily_search/     # 核心包
│   ├── server.py          # 服务器实现
│   ├── client.py          # Tavily API 客户端
│   ├── test_server.py     # 服务器测试
│   ├── test_client.py     # 客户端测试
│   └── __init__.py        # 包初始化
├── .env                   # 环境配置
├── README.md              # 文档
└── pyproject.toml         # 项目配置

关键组件

服务器 (server.py)

• 我已经实现了 MCP 协议
• 请求处理和路由
• 错误恢复和健康监控

客户端 (client.py)

• Tavily API 集成
• 具有指数退避的重试机制
• 结果格式化和处理
• 错误处理和日志记录

测试 (test_server.py 和 test_client.py)

• 服务器和客户端的全面单元测试
• 确保实现的可靠性和正确性

使用示例

以下是我实现的一些增强搜索功能的示例：

1. 基本搜索：

{
  "name": "search",
  "arguments": {
    "query": "Latest news on artificial intelligence"
  }
}

2. 带有图像的高级搜索：

{
  "name": "search",
  "arguments": {
    "query": "Elon Musk SpaceX achievements",
    "search_depth": "advanced",
    "include_images": true,
    "max_results": 10
  }
}

3. 新闻特定搜索：

{
  "name": "search",
  "arguments": {
    "query": "Climate change impact on agriculture",
    "topic": "news",
    "max_results": 5
  }
}

4. 搜索原始内容：

{
  "name": "search",
  "arguments": {
    "query": "Python programming best practices",
    "include_raw_content": true,
    "max_results": 3
  }
}

故障排除指南

连接问题

如果事情没有按预期进行，请按照我概述的这些步骤操作：

1. 验证您的配置路径
2. 检查 Claude Desktop 日志：

   # Windows
   type %APPDATA%\Claude\logs\latest.log
   # Unix/MacOS
   cat ~/.config/Claude/logs/latest.log
   

3. 使用快速启动命令手动测试服务器

API 故障排除

如果您遇到 API 问题：

1. 验证您的 API 密钥权限
2. 检查您的网络连接
3. 监控服务器日志中的 API 响应

运行测试

要运行此项目的单元测试，请按照以下步骤操作：

1. 安装开发依赖项：

   uv pip install -e ".[dev]"
   

2. 使用 pytest 运行测试：

   pytest mcp_tavily_search
   

这将在 mcp_tavily_search 目录中运行所有测试，包括 test_client.py 和 test_server.py。

社区与支持

• 我鼓励您在 GitHub 上报告问题并做出贡献
• 分享您的实现和改进
• 加入我们的讨论并帮助他人

安全与最佳实践

安全是我实现中的重中之重。 服务器包括：

• 通过环境变量安全处理 API 密钥
• 自动请求超时管理
• 全面的错误跟踪和日志记录

许可证

我已根据 MIT 许可协议许可了此项目。 有关详细信息，请参见 LICENSE 文件。

致谢

我要特别感谢：

• 创新的 Tavily API 团队
• MCP 协议社区