Tavily Web Search MCP Server

Ein MCP-Dienst für Websuche, entwickelt auf Basis des offiziellen Tavily Python SDK, implementiert mit dem standardmäßigen MCP Python SDK, unter Verwendung des Streamable HTTP-Übertragungsprotokolls, bereitgestellt über FastAPI + uvicorn.

Funktionen

Der Dienst bietet 8 MCP-Tools, die die Hauptfunktionen des offiziellen Tavily SDK abdecken:

Die Forschungsaufgaben, die deep_research_start / deep_research_result entsprechen, werden asynchron auf dem Tavily-Server ausgeführt und können mehrere Minuten dauern. Rufen Sie zuerst deep_research_start auf, um die request_id zu erhalten, und verwenden Sie dann deep_research_result, um abzufragen, bis der status completed (oder failed) ist.

Related MCP server: tavily-pool-mcp

Verzeichnisstruktur

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

Umgebungsanforderungen

• Python 3.12 (lokal über die Conda-Umgebung llm_factory_envs entwickelt, auf dem Remote-Server wird llm_env verwendet)

• Tavily API Key (unter app.tavily.com beantragen)

Lokale Entwicklung und Tests

1. Umgebungsvariablen vorbereiten

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

2. Abhängigkeiten installieren (Conda-Umgebung llm_factory_envs)

conda activate llm_factory_envs
pip install -r requirements.txt

3. MCP-Dienst starten

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

4. Mit Testclient verifizieren

Öffnen Sie ein weiteres Terminal:

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

Der Testclient führt nacheinander aus: Verbindung zum Dienst herstellen → verfügbare Tools auflisten → web_search / web_fetch / web_crawl / web_map / qna_search / search_context aufrufen und die Ergebnisse ausgeben.

Deep-Research-Aufgaben dauern länger (möglicherweise mehrere Minuten) und werden standardmäßig nicht getestet. Um auch deep_research_start / deep_research_result zu verifizieren:

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 "近期国产大模型有哪些重要发布"

In diesem Modus wird nach dem Einreichen der Aufgabe alle 10 Sekunden deep_research_result abgefragt, bis der Status completed / failed ist.

Bereitstellung auf dem Remote-Server

Remote-Server-Informationen: 101.47.67.15, Bereitstellung über SSH (passwortloses Login bereits konfiguriert), Verwendung der Remote-Conda-Umgebung llm_env, Dienstport fest auf 20260.

1. Remote-.env konfigurieren

In der lokalen .env MCP_HOST auf 0.0.0.0 ändern (für öffentliche Netzwerke), MCP_PORT auf 20260 belassen. Das Bereitstellungsskript synchronisiert die .env automatisch per scp (falls remote und lokal unterschiedliche Keys verwendet werden sollen, kann /opt/tavily-mcp-server/.env direkt auf dem Remote-Server manuell gepflegt werden).

2. Ein-Klick-Bereitstellung

bash deploy/deploy.sh

Das Skript führt Folgendes aus:

1. rsync der Projektdateien nach root@101.47.67.15:/opt/tavily-mcp-server (unter Ausschluss von .git, __pycache__ usw.)

2. Synchronisierung der .env (falls lokal vorhanden)

3. Installation der Abhängigkeiten in der Remote-Umgebung llm_env

4. Installation/Aktualisierung des systemd-Dienstes und Neustart

3. Server-Firewall / Sicherheitsgruppe

Bitte stellen Sie sicher, dass die Sicherheitsgruppenregeln in der Cloud-Konsole den TCP-Port 20260 freigeben (deploy.sh ändert die Cloud-Sicherheitsgruppe nicht automatisch; dies muss manuell in der Konsole des Anbieters erfolgen). Falls auf dem Server firewalld/ufw aktiviert ist, muss der Port ebenfalls freigegeben werden, z. B.:

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

4. Remote-Bereitstellung verifizieren

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

Häufige Betriebsbefehle

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-Client-Konfiguration

Nach der Bereitstellung kann der Dienst in jedem MCP-Client, der Streamable HTTP unterstützt, über die folgende JSON-Konfiguration eingebunden werden:

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

Für lokale Tests ersetzen Sie url durch http://127.0.0.1:20260/mcp.

Erläuterung der Umgebungsvariablen

Sicherheitshinweise

• Die .env-Datei ist in .gitignore ausgeschlossen; niemals in ein GitHub-Repository committen.

• Keine Schlüssel im Code hartkodieren; alle sensiblen Informationen werden über Umgebungsvariablen injiziert (dynamisch geladen mit python-dotenv).

• Vor dem Committen von Code erneut prüfen, dass git status keine .env oder andere Dateien mit Schlüsseln enthält.