Tavily MCP 服务器

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

特征

可用工具

tavily_web_search - 通过人工智能内容提取执行全面的网络搜索。
- query （字符串，必需）：搜索查询
- max_results （整数，可选）：返回的最大结果数（默认值：5，最大值：20）
- search_depth （字符串，可选）：搜索深度为“基本”或“高级”（默认值为“基本”）
- include_domains （列表或字符串，可选）：结果中具体包含的域列表
- exclude_domains （列表或字符串，可选）：要从结果中排除的域列表
tavily_answer_search - 执行网络搜索并生成带有支持证据的直接答案。
- query （字符串，必需）：搜索查询
- max_results （整数，可选）：返回的最大结果数（默认值：5，最大值：20）
- search_depth （字符串，可选）：搜索深度为“基本”或“高级”（默认值为“高级”）
- 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 的新闻搜索功能搜索最近的新闻文章

Related MCP server: Tavily MCP Server

先决条件

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

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

与 VS Code 一起使用

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

在 VS Code 中使用 UV 安装在 VS Code Insiders 中使用 UV 安装

如需手动安装，请将以下 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即可找到确切的路径。

使用示例

对于常规网络搜索：

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

测试

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

安装测试依赖项：

source .venv/bin/activate  # If using a virtual environment
uv sync --dev  # Or: 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 检查器来调试服务器：

# 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 的改进做出贡献！您可以通过以下方式提供帮助：

分叉存储库
创建功能分支（ git checkout -b feature/amazing-feature ）
进行更改
运行测试以确保通过
提交您的更改（ git commit -m 'Add amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

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

执照

mcp-tavily 采用 MIT 许可证。详情请参阅许可证文件。

Tavily MCP Server