使用说明

########################################################

弃用通知

我在2025年3月初构建了这个MCP服务器，当时MCP协议是全新的，在聊天机器人中没有一致的搜索方法，早于其他实现。

从那以后，塔维利的好人释放了他们的官员 Tavily MCP服务器该系统维护良好，并与他们的最新能力保持同步。因此，我现在弃用这台服务器，转而支持他们的服务器。

########################################################

Tavily MCP服务器

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

特性

可用工具

tavily_web_search -通过AI驱动的内容提取执行全面的网络搜索。
- 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的人工智能搜索引擎搜索网络
tavily_answer_search -搜索网络，获得人工智能生成的答案和支持证据
tavily新闻搜索 -使用Tavily的新闻搜索功能搜索最近的新闻文章

先决条件

Python 3.11或更高版本
Tavilly 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代码

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

对于手动安装，请将以下JSON块添加到VS Code中的用户设置（JSON）文件中。您可以按 Ctrl + Shift + P 和打字 Preferences: Open User Settings (JSON).

您可以选择将其添加到名为的文件中 .vscode/mcp.json 在您的工作空间中。这将允许您与他人共享配置。

请注意 mcp 中不需要密钥 .vscode/mcp.json 文件。

{
  "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密钥，该密钥可以通过三种方式提供：

通过a .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
# Or using Make
make test

依赖兼容性测试

要确保项目使用最新的依赖关系版本，请使用以下命令：

# Test with latest dependencies using Make
make test-deps

# Full compatibility test with verbose output
make test-compatibility

# Or use the standalone script
./scripts/test-compatibility.sh

这些命令将：

将所有依赖项更新为最新版本
运行覆盖率高的完整测试套件
报告任何兼容性问题
显示版本更改以提高透明度

自动化测试

该项目包括通过GitHub Actions进行自动化依赖兼容性测试：

每周测试：每周一上午8点运行（UTC）
多Python支持：针对Python 3.11、3.12和3.13的测试
问题创建：测试失败时自动创建GitHub问题
手动触发：可以从GitHub Actions选项卡手动触发

了解测试结果

当测试通过时：您的项目与最新的依赖关系版本兼容。您可以安全地更新需求文件。

当测试失败时：查看测试输出以识别破坏性更改，更新代码以处理API更改，如果需要更新测试，或者考虑固定有问题的依赖版本。

测试输出示例

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

======================================================= 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功能是否正常工作，包括域过滤器和各种输入格式的处理。

发布管理

该项目包括用于构建和发布最新依赖版本的工具：

使用最新依赖项进行构建

# Build package with latest dependency versions
make build-latest

# Complete release workflow: test, build, and check with latest deps
make release-all

# Prepare a release with version management
./scripts/prepare-release.sh [new_version]

发布工作流

对于具有最新依赖项的版本，建议采用以下方法：

完成发布准备: make release-all
上传时不降级: make upload-latest

替代性分步方法：

使用最新依赖项进行测试: make test-compatibility
为发布而构建: make release-build
上传而不重建: make upload-latest

一个命令发布和发布：

make release-publish

重要：使用 make upload-latest 而不是 make upload 以防止在上传过程中依赖性降级。这 upload-latest 命令使用现有的分发文件，而不重新安装依赖项。

发布命令确保您的包是使用最新的兼容依赖版本构建和测试的，从而防止了传统构建链可能出现的降级。

码头工人

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

复刻仓库
创建要素分支(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许可证获得许可。请参阅许可证文件以获取详细信息。