Tavily Web Search MCP Server

Tavily 公式 Python SDK をベースに開発されたネット検索 MCP サービスです。標準の MCP Python SDK を使用し、Streamable HTTP 転送プロトコルを採用、FastAPI + uvicorn を通じて外部にサービスを提供します。

機能

サービスは 8 つの MCP ツールを提供し、Tavily 公式 SDK の主要機能をカバーしています：

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 のままにします。その後デプロイスクリプトを実行すると、scp で .env が自動的に同期されます（リモートとローカルで異なるキーを使用する場合は、リモートで直接 /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 クライアント設定

デプロイ完了後、Streamable HTTP をサポートする任意の MCP クライアントで、以下の 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 やその他のキーを含むファイルが含まれていないことを再度確認してください。