Tavily Web Search MCP Server

A web-search MCP service built on the official Tavily Python SDK, implemented with the standard MCP Python SDK, using the Streamable HTTP transport protocol and served externally via FastAPI + uvicorn.

Features

The service provides 8 MCP tools covering the main capabilities of the official Tavily SDK:

The research tasks corresponding to deep_research_start / deep_research_result run asynchronously on the Tavily server side and may take several minutes. First call deep_research_start to get a request_id, then poll with deep_research_result until status becomes completed (or failed).

Related MCP server: tavily-pool-mcp

Directory Structure

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

Environment Requirements

• Python 3.12 (developed locally via the conda environment llm_factory_envs; the remote server uses llm_env)

• Tavily API Key (apply at app.tavily.com)

Local Development and Testing

1. Prepare Environment Variables

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

2. Install Dependencies (conda environment llm_factory_envs)

conda activate llm_factory_envs
pip install -r requirements.txt

3. Start the MCP Service

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

4. Verify with the Test Client

Open another terminal:

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

The test client will, in sequence: connect to the service → list available tools → call web_search / web_fetch / web_crawl / web_map / qna_search / search_context, and print the results.

Deep research tasks take a long time (potentially several minutes) and are not tested by default. To also verify 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 "近期国产大模型有哪些重要发布"

This mode polls deep_research_result every 10 seconds after submitting the task, until the status becomes completed / failed.

Deploying to a Remote Server

Remote server details: 101.47.67.15, deployed over SSH (passwordless login already configured), using the remote conda environment llm_env, with the service port fixed at 20260.

1. Configure the Remote .env

In the local .env, change MCP_HOST to 0.0.0.0 (listen on the public network) and keep MCP_PORT at 20260. Running the deployment script will then automatically sync .env via scp (if the remote and local environments need to use different keys, you can manually maintain /opt/tavily-mcp-server/.env directly on the remote server).

2. One-Click Deployment

bash deploy/deploy.sh

This script will:

1. rsync project files to root@101.47.67.15:/opt/tavily-mcp-server (excluding .git, __pycache__, etc.)

2. Sync .env (if it exists locally)

3. Install dependencies in the remote llm_env environment

4. Install/update the systemd service and restart it

3. Server Firewall / Security Group

Please confirm that the security group rules in your cloud provider's console already allow TCP port 20260 (deploy.sh does not automatically modify cloud security groups; you need to open it manually in the provider's console). If the server itself has firewalld/ufw enabled, you also need to allow this port, for example:

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

4. Verify the Remote Deployment

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

Common Operations Commands

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 Configuration

After deployment, you can connect to this service from any MCP client that supports Streamable HTTP using the following JSON configuration:

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

For local integration testing, simply replace url with http://127.0.0.1:20260/mcp.

Environment Variables

Security Notes

• The .env file is already excluded in .gitignore; never commit it to a GitHub repository.

• Do not hardcode any secrets in the code; all sensitive information is injected via environment variables (loaded dynamically with python-dotenv).

• Before committing code, double-check that git status does not contain .env or any other files containing secrets.