mcp-塔维利
项目介绍
Tavily MCP 服务器
一个提供 AI 驱动的网络搜索功能的模型上下文协议服务器，使用 Tavily 的搜索 API。此服务器使大型语言模型能够执行复杂的网络搜索，获取问题的直接答案，并搜索带有 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 的网站 获取）
uvPython 包管理器（推荐）
安装
选项 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。排除维基百科来源。
使用答案搜索模式获取直接答案：
我想要一个由当前网络资源支持的具体答案：红木树的平均寿命是多少？
进行新闻搜索：
给我过去 5 天内排名前十的 AI 相关新闻
测试
项目包括一个全面的测试套件，具有自动化的依赖兼容性测试。
运行测试
-
安装测试依赖：
source .venv/bin/activate # 如果使用虚拟环境 uv sync --dev # 或: pip install -r requirements-dev.txt -
运行标准测试套件：
./tests/run_tests.sh # 或使用 Make make test
依赖兼容性测试
为了确保项目与最新的依赖版本兼容，使用以下命令：
# 使用 Make 测试最新依赖
make test-deps
# 完全兼容性测试，带详细输出
make test-compatibility
# 或使用独立脚本
./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 功能是否正确工作，包括域名过滤器和各种输入格式的处理。
发布管理
项目包括用于构建和发布最新依赖版本的工具：
使用最新依赖构建
# 使用最新依赖版本构建包
make build-latest
# 完整发布流程：测试、构建和检查最新依赖
make release-all
# 准备发布并管理版本
./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
构建 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！以下是你可以帮助的方式：
- 叉仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 进行更改
- 运行测试以确保它们通过
- 提交更改（
git commit -m '添加了神奇的功能'） - 推送到分支（
git push origin feature/amazing-feature） - 开启 Pull Request
有关其他 MCP 服务器和实现模式的示例，请参见： https://github.com/modelcontextprotocol/servers
许可证
mcp-tavily 采用 MIT 许可证。详情请参阅 LICENSE 文件。