Tavily MCP 服务器

一个使用 Tavily 搜索 API 提供基于 AI 的网络搜索功能的模型上下文协议服务器。该服务器使大语言模型能够执行复杂的网络搜索，直接回答问题，并通过 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

# With pip
pip install mcp-tavily

# Or with uv (recommended)
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: 从源代码安装

# Clone the repository
git clone https://github.com/RamXX/mcp-tavily.git
cd mcp-tavily

# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies and build
uv sync  # Or: pip install -r requirements.txt
uv build  # Or: pip install -e .

# To install with test dependencies:
uv sync --dev  # Or: pip install -r requirements-dev.txt

在安装过程中，你应该会看到包及其依赖项正在被构建和安装。

配置

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 来找到确切路径。

使用示例

对于常规网页搜索：

Tell me about Anthropic's newly released MCP protocol

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

Tell me about redwood trees. Please use MLA format in markdown syntax and include the URLs in the citations. Exclude Wikipedia sources.

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

I want a concrete answer backed by current web sources: What is the average lifespan of redwood trees?

进行新闻搜索：

Give me the top 10 AI-related news in the last 5 days

测试

该项目包含一个全面的测试套件。要运行测试，请执行以下步骤：

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 检查器来调试服务器：

# Using npx
npx @modelcontextprotocol/inspector python -m mcp_server_tavily

# For development
cd path/to/mcp-tavily
npx @modelcontextprotocol/inspector python -m mcp_server_tavily

贡献

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

1. 分叉仓库
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 文件了解详细信息。