Servidor MCP de Búsqueda Web de Tavily

Servicio MCP de búsqueda en línea desarrollado sobre el SDK oficial de Python de Tavily, implementado con el SDK estándar de MCP para Python, utilizando el protocolo de transporte Streamable HTTP, y expuesto mediante FastAPI + uvicorn.

Funcionalidades

El servicio ofrece 8 herramientas MCP que cubren las principales capacidades del SDK oficial de Tavily:

Las tareas de investigación correspondientes a deep_research_start / deep_research_result se ejecutan de forma asíncrona en el servidor de Tavily y pueden tardar varios minutos. Llame primero a deep_research_start para obtener el request_id y luego use deep_research_result para sondear hasta que el status cambie a completed (o failed).

Related MCP server: tavily-pool-mcp

Estructura de directorios

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

Requisitos del entorno

• Python 3.12 (desarrollado localmente con el entorno conda llm_factory_envs; en el servidor remoto se usa llm_env)

• Clave API de Tavily (solicitarla en app.tavily.com)

Desarrollo y pruebas locales

1. Preparar las variables de entorno

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

2. Instalar dependencias (entorno conda llm_factory_envs)

conda activate llm_factory_envs
pip install -r requirements.txt

3. Iniciar el servicio MCP

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

4. Verificar con el cliente de pruebas

Abra otro terminal:

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

El cliente de pruebas realizará secuencialmente: conectar al servicio → listar las herramientas disponibles → invocar web_search / web_fetch / web_crawl / web_map / qna_search / search_context, e imprimirá los resultados.

Las tareas de investigación profunda requieren bastante tiempo (pueden tardar varios minutos) y no se prueban por defecto. Si desea verificar también 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 "近期国产大模型有哪些重要发布"

Este modo envía la tarea y luego sondea deep_research_result cada 10 segundos hasta que el estado cambie a completed / failed.

Despliegue en el servidor remoto

Información del servidor remoto: 101.47.67.15, se despliega mediante SSH (con autenticación sin contraseña ya configurada), usando el entorno conda remoto llm_env; el puerto del servicio está fijado en 20260.

1. Configurar el .env remoto

En el .env local, cambie MCP_HOST a 0.0.0.0 (para escuchar en la red pública), mantenga MCP_PORT en 20260, y al ejecutar el script de despliegue se sincronizará automáticamente el .env mediante scp (si necesita usar una clave diferente en remoto y en local, puede mantener manualmente /opt/tavily-mcp-server/.env directamente en el servidor remoto).

2. Despliegue con un solo clic

bash deploy/deploy.sh

Este script:

1. Sincroniza los archivos del proyecto a root@101.47.67.15:/opt/tavily-mcp-server con rsync (excluyendo .git, __pycache__, etc.)

2. Sincroniza el .env (si existe localmente)

3. Instala las dependencias en el entorno remoto llm_env

4. Instala/actualiza el servicio systemd y lo reinicia

3. Cortafuegos del servidor / grupo de seguridad

Confirme que las reglas del grupo de seguridad de la consola del proveedor de la nube permiten el tráfico TCP en el puerto 20260 (deploy.sh no modifica automáticamente el grupo de seguridad de la nube; debe abrirlo manualmente en la consola del proveedor). Si el servidor tiene habilitado firewalld/ufw, también debe permitir ese puerto, por ejemplo:

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

4. Verificar el despliegue remoto

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

Comandos comunes de operación y mantenimiento

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"

Configuración del cliente MCP

Una vez desplegado, puede conectar este servicio desde cualquier cliente MCP compatible con Streamable HTTP mediante la siguiente configuración JSON:

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

Para pruebas locales, sustituya url por http://127.0.0.1:20260/mcp.

Descripción de las variables de entorno

Notas de seguridad

• El archivo .env está excluido en .gitignore; no lo suba nunca al repositorio de GitHub.

• No codifique ninguna clave en el código; toda la información sensible se inyecta mediante variables de entorno (carga dinámica con python-dotenv).

• Antes de enviar el código, vuelva a comprobar con git status que no se incluyen .env ni otros archivos con claves.