Tavily MCP 服务器

一个模型上下文协议服务器，它使用 Tavily 的搜索 API 提供 AI 驱动的网页搜索功能。该服务器使 LLM 能够执行复杂的网页搜索，获得问题的直接答案，并搜索包含 AI 提取的相关内容的最新新闻文章。

功能

可用工具

• tavily_web_search - 执行全面的网页搜索，并使用 AI 驱动的内容提取。

  • query (字符串，必需): 搜索查询
  • max_results (整数，可选): 返回的最大结果数 (默认: 5, 最大: 20)
  • search_depth (字符串，可选): "basic" 或 "advanced" 搜索深度 (默认: "basic")
  • include_domains (列表或字符串，可选): 要专门包含在结果中的域名列表
  • exclude_domains (列表或字符串，可选): 要从结果中排除的域名列表

• tavily_answer_search - 执行网页搜索并生成带有支持证据的直接答案。

  • query (字符串，必需): 搜索查询
  • max_results (整数，可选): 返回的最大结果数 (默认: 5, 最大: 20)
  • search_depth (字符串，可选): "basic" 或 "advanced" 搜索深度 (默认: "advanced")
  • include_domains (列表或字符串，可选): 要专门包含在结果中的域名列表
  • exclude_domains (列表或字符串，可选): 要从结果中排除的域名列表

• tavily_news_search - 搜索带有发布日期的最新新闻文章。

  • query (字符串，必需): 搜索查询
  • max_results (整数，可选): 返回的最大结果数 (默认: 5, 最大: 20)
  • days (整数，可选): 要搜索的天数 (默认: 3)
  • include_domains (列表或字符串，可选): 要专门包含在结果中的域名列表
  • exclude_domains (列表或字符串，可选): 要从结果中排除的域名列表

提示语

该服务器还为每种搜索类型提供提示模板：

• tavily_web_search - 使用 Tavily 的 AI 驱动的搜索引擎搜索网络
• tavily_answer_search - 搜索网络并获得 AI 生成的答案以及支持证据
• tavily_news_search - 使用 Tavily 的新闻搜索搜索最新新闻文章

前提条件

• Python 3.11 或更高版本
• 一个 Tavily API 密钥 (从 Tavily 的网站 获取)
• uv Python 包管理器 (推荐)

安装

选项 1：使用 pip 或 uv

# 使用 pip
pip install mcp-tavily

# 或者使用 uv (推荐)
uv add mcp-tavily

您应该看到类似于以下的输出：

Resolved packages: mcp-tavily, mcp, pydantic, python-dotenv, tavily-python [...]
Successfully installed mcp-tavily-0.1.4 mcp-1.0.0 [...]

选项 2：从源代码

# 克隆存储库
git clone https://github.com/RamXX/mcp-tavily.git
cd mcp-tavily

# 创建一个虚拟环境 (可选但推荐)
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上: .venv\Scripts\activate

# 安装依赖项并构建
uv sync  # 或者: pip install -r requirements.txt
uv build  # 或者: pip install -e .

# 要安装测试依赖项：
uv sync --dev  # 或者: pip install -r requirements-dev.txt

在安装过程中，您应该看到正在构建和安装的软件包及其依赖项。

在 VS Code 中使用

为了快速安装，请使用以下一键安装按钮之一：

对于手动安装，请将以下 JSON 块添加到 VS Code 中的用户设置 (JSON) 文件。您可以通过按 Ctrl + Shift + P 并键入 Preferences: Open User Settings (JSON) 来执行此操作。

或者，您可以将其添加到工作区中名为 .vscode/mcp.json 的文件中。这将允许您与他人共享配置。

请注意，.vscode/mcp.json 文件中不需要 mcp 键。

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Tavily API Key",
        "password": true
      }
    ],
    "servers": {
      "tavily": {
        "command": "uvx",
        "args": ["mcp-tavily"],
        "env": {
          "TAVILY_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

配置

API 密钥设置

服务器需要一个 Tavily API 密钥，可以通过三种方式提供：

1. 通过项目目录中的 .env 文件：

   TAVILY_API_KEY=your_api_key_here
   

2. 作为环境变量：

   export TAVILY_API_KEY=your_api_key_here
   

3. 作为命令行参数：

   python -m mcp_server_tavily --api-key=your_api_key_here
   

为 Claude.app 配置

添加到您的 Claude 设置：

"mcpServers": {
  "tavily": {
    "command": "python",
    "args": ["-m", "mcp_server_tavily"]
  },
  "env": {
    "TAVILY_API_KEY": "your_api_key_here"
  }
}

如果遇到问题，您可能需要指定 Python 解释器的完整路径。运行 which python 查找确切路径。

使用示例

对于常规网页搜索：

告诉我 Anthropic 新发布的 MCP 协议

要生成带有域过滤的报告：

告诉我关于红杉树的信息。请使用 MLA 格式的 markdown 语法，并在引文中包含 URL。排除维基百科来源。

要使用答案搜索模式获取直接答案：

我想要一个由当前网络来源支持的具体答案：红杉树的平均寿命是多少？

对于新闻搜索：

给我过去 5 天中与 AI 相关的 10 大新闻

测试

该项目包含一个全面的测试套件。要运行测试：

1. 安装测试依赖项：

   source .venv/bin/activate  # 如果使用虚拟环境
   uv sync --dev  # 或者: pip install -r requirements-dev.txt
   

2. 运行测试：

   ./tests/run_tests.sh
   

您应该看到类似于以下的输出：

============================= test session starts ==============================
collected 27 items

tests/test_models.py ................. [ 62%]
tests/test_utils.py ..... [ 81%]
tests/test_integration.py ..... [100%]

---------- coverage: platform darwin, python 3.13.2-final-0 ----------
Name                                Stmts   Miss  Cover
-------------------------------------------------------
src/mcp_server_tavily/__init__.py      16      2    88%
src/mcp_server_tavily/__main__.py       2      2     0%
src/mcp_server_tavily/server.py       137     80    42%
-------------------------------------------------------
TOTAL                                 155     84    46%


============================== 27 passed in 0.40s ==============================

测试套件包括数据模型、实用程序函数、集成测试、错误处理和参数验证的测试。它侧重于验证所有 API 功能是否正常工作，包括域过滤器和各种输入格式的处理。

调试

您可以使用 MCP 检查器来调试服务器：

# 使用 npx
npx @modelcontextprotocol/inspector python -m mcp_server_tavily

# 用于开发
cd path/to/mcp-tavily
npx @modelcontextprotocol/inspector python -m mcp_server_tavily

贡献

我们欢迎贡献来改进 mcp-tavily！以下是您可以提供帮助的方式：

1. Fork 存储库
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试以确保它们通过
5. 提交您的更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开一个 Pull Request

有关其他 MCP 服务器和实现模式的示例，请参见： https://github.com/modelcontextprotocol/servers

许可证

mcp-tavily 在 MIT 许可证下获得许可。有关详细信息，请参见 LICENSE 文件。