Tavily Web Search MCP Server

Веб-поисковый MCP-сервис, разработанный на основе официального Python SDK Tavily, реализованный с использованием стандартного MCP Python SDK, работающий по транспортному протоколу Streamable HTTP и предоставляющий услуги через FastAPI + uvicorn.

Возможности

Сервис предоставляет 8 инструментов MCP, охватывающих основные возможности официального SDK Tavily:

Задачи исследования, соответствующие deep_research_start / deep_research_result, выполняются асинхронно на стороне сервера Tavily и могут занять несколько минут. Сначала вызовите deep_research_start, чтобы получить request_id, затем опрашивайте deep_research_result, пока status не станет completed (или failed).

Related MCP server: tavily-pool-mcp

Структура каталогов

tavily-mcp-server/
├── app/
│   ├── config.py       # 环境变量配置加载（.env）
│   ├── tavily_tools.py # TavilyToolkit：封装 web_search / web_fetch
│   ├── server.py        # FastMCP 实例与工具注册
│   └── main.py          # FastAPI 应用 + uvicorn 入口，挂载 Streamable HTTP
├── client/
│   └── test_client.py   # 本地测试客户端（连接 MCP 服务并调用工具）
├── deploy/
│   ├── deploy.sh                # 一键同步 + 部署到远程服务器
│   └── tavily-mcp.service       # systemd 服务单元
├── requirements.txt
├── .env.example
└── .gitignore

Требования к окружению

• Python 3.12 (локальная разработка в conda-среде llm_factory_envs, на удалённом сервере используется llm_env)

• Tavily API Key (получить на app.tavily.com)

Локальная разработка и тестирование

1. Настройка переменных окружения

cp .env.example .env
# 编辑 .env，填入 TAVILY_API_KEY；本地测试保持 MCP_HOST=127.0.0.1

2. Установка зависимостей (conda-среда llm_factory_envs)

conda activate llm_factory_envs
pip install -r requirements.txt

3. Запуск MCP-сервиса

python -m app.main
# 服务启动后监听 http://127.0.0.1:20260/mcp
# 健康检查: curl http://127.0.0.1:20260/health

4. Проверка с помощью тестового клиента

Откройте ещё один терминал:

conda activate llm_factory_envs
python -m client.test_client --url http://127.0.0.1:20260/mcp

Тестовый клиент последовательно: подключится к сервису → выведет список доступных инструментов → вызовет web_search / web_fetch / web_crawl / web_map / qna_search / search_context и выведет результаты.

Задачи глубокого исследования занимают много времени (возможно, несколько минут), по умолчанию не тестируются. Чтобы также проверить deep_research_start / deep_research_result:

python -m client.test_client --url http://127.0.0.1:20260/mcp --deep-research
# 也可自定义研究任务描述:
python -m client.test_client --url http://127.0.0.1:20260/mcp --deep-research "近期国产大模型有哪些重要发布"

В этом режиме после отправки задачи каждые 10 секунд будет опрашиваться deep_research_result, пока статус не станет completed / failed.

Развёртывание на удалённом сервере

Информация об удалённом сервере: 101.47.67.15, развёртывание по SSH (настроен вход по ключу), используется удалённая conda-среда llm_env, порт сервиса зафиксирован как 20260.

1. Настройка удалённого .env

В локальном .env измените MCP_HOST на 0.0.0.0 (прослушивание на всех интерфейсах), MCP_PORT оставьте 20260, затем запустите скрипт развёртывания, который автоматически синхронизирует .env через scp (если для удалённого и локального окружения нужны разные ключи, можно вручную поддерживать /opt/tavily-mcp-server/.env на сервере).

2. Развёртывание одной командой

bash deploy/deploy.sh

Этот скрипт:

1. Синхронизирует файлы проекта через rsync в root@101.47.67.15:/opt/tavily-mcp-server (исключая .git, __pycache__ и т.д.)

2. Синхронизирует .env (если существует локально)

3. Устанавливает зависимости в удалённой среде llm_env

4. Устанавливает/обновляет службу systemd и перезапускает её

3. Брандмауэр / группа безопасности сервера

Убедитесь, что правила группы безопасности в консоли облачного провайдера разрешают TCP-порт 20260 (deploy.sh не изменяет группу безопасности автоматически, его нужно открыть вручную в консоли провайдера). Если на сервере включён firewalld/ufw, также необходимо разрешить этот порт, например:

# firewalld
ssh root@101.47.67.15 "firewall-cmd --permanent --add-port=20260/tcp && firewall-cmd --reload"

4. Проверка удалённого развёртывания

curl http://101.47.67.15:20260/health
python -m client.test_client --url http://101.47.67.15:20260/mcp

Часто используемые команды администрирования

ssh root@101.47.67.15 "systemctl status tavily-mcp.service --no-pager"
ssh root@101.47.67.15 "journalctl -u tavily-mcp.service -f"
ssh root@101.47.67.15 "systemctl restart tavily-mcp.service"

Настройка MCP-клиента

После завершения развёртывания вы можете подключиться к сервису в любом MCP-клиенте, поддерживающем Streamable HTTP, с помощью следующей JSON-конфигурации:

{
  "mcpServers": {
    "tavily-web-search": {
      "type": "streamable_http",
      "url": "http://101.47.67.15:20260/mcp"
    }
  }
}

Для локальной отладки замените url на http://127.0.0.1:20260/mcp.

Описание переменных окружения

Меры безопасности

• Файл .env исключён в .gitignore, не загружайте его в репозиторий GitHub.

• Не жёстко задавайте ключи в коде, все конфиденциальные данные передаются через переменные окружения (динамическая загрузка через python-dotenv).

• Перед коммитом убедитесь, что git status не содержит .env или других файлов с ключами.