Tavily MCP 服务器

一个模型上下文协议服务器，使用 Tavily 的搜索 API 提供 AI 驱动的网络搜索功能。该服务器使大型语言模型（LLMs）能够执行复杂的网络搜索、获取问题的直接答案，并搜索最近的新闻文章，同时提取 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 密钥，可以通过以下三种方式提供：

通过项目目录中的 .env 文件：
```
TAVILY_API_KEY=your_api_key_here
```

作为环境变量：

export TAVILY_API_KEY=your_api_key_here

作为命令行参数：

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。排除 Wikipedia 来源。

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

我想要一个基于当前网络来源的具体答案：红木树的平均寿命是多少？

对于新闻搜索：

给我过去 5 天内前 10 条与 AI 相关的新闻

测试

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

安装测试依赖：

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

运行测试：
```
./tests/run_tests.sh
```

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

======================================================= test session starts ========================================================
platform darwin -- Python 3.13.3, pytest-8.3.5, pluggy-1.5.0
rootdir: /Users/ramirosalas/workspace/mcp-tavily
configfile: pyproject.toml
plugins: cov-6.0.0, asyncio-0.25.3, anyio-4.8.0, mock-3.14.0
asyncio: mode=Mode.STRICT, asyncio_default_fixture_loop_scope=function
collected 50 items                                                                                                                 

tests/test_docker.py ..                                                                                                      [  4%]
tests/test_integration.py .....                                                                                              [ 14%]
tests/test_models.py .................                                                                                       [ 48%]
tests/test_server_api.py .....................                                                                               [ 90%]
tests/test_utils.py .....                                                                                                    [100%]

---------- coverage: platform darwin, python 3.13.3-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       149     16    89%
-------------------------------------------------------
TOTAL                                 167     20    88%

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

Docker

构建 Docker 镜像：

make docker-build

或者直接使用 Docker 构建：

docker build -t mcp_tavily .

运行一个分离的 Docker 容器（默认名称 mcp_tavily_container，端口 8000 → 8000）：

make docker-run

或者手动运行：

docker run -d --name mcp_tavily_container \
  -e TAVILY_API_KEY=your_api_key_here \
  -p 8000:8000 mcp_tavily

停止并删除容器：

make docker-stop

查看容器日志：

make docker-logs

您可以通过设置环境变量来覆盖默认值：

DOCKER_IMAGE: 镜像名称（默认 mcp_tavily）
DOCKER_CONTAINER: 容器名称（默认 mcp_tavily_container）
HOST_PORT: 绑定的主机端口（默认 8000）
CONTAINER_PORT: 容器端口（默认 8000）

调试

您可以使用 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 做出贡献！以下是您可以提供帮助的方式：

Fork 仓库
创建一个特性分支（git checkout -b feature/amazing-feature）
进行更改
运行测试以确保它们通过
提交更改（git commit -m 'Add amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开一个 Pull Request

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

许可证

mcp-tavily 采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。