Tavily Search

Búsqueda web impulsada por IA utilizando la API de Tavily Search.

GitHub
72
Prueba este MCPPatrocinado

Documentación

########################################################

Aviso de descontinuación

Construí este servidor MCP a principios de marzo de 2025, cuando el protocolo MCP era completamente nuevo y no existían formas consistentes de realizar búsquedas en chatbots, anticipándome a otras implementaciones.

Desde entonces, los buenos amigos de Tavily han lanzado su servidor MCP oficial de Tavily, que está bien mantenido y sincronizado con sus últimas capacidades. Por lo tanto, ahora estoy descontinuando este servidor en favor del suyo.

########################################################

Servidor MCP de Tavily

Un servidor de Protocolo de Contexto de Modelo que proporciona capacidades de búsqueda web impulsadas por IA utilizando la API de búsqueda de Tavily. Este servidor permite a los LLM realizar búsquedas web sofisticadas, obtener respuestas directas a preguntas y buscar artículos de noticias recientes con contenido relevante extraído por IA.

Características

Herramientas disponibles

  • tavily_web_search - Realiza búsquedas web exhaustivas con extracción de contenido impulsada por IA.

    • query (cadena, obligatorio): Consulta de búsqueda
    • max_results (entero, opcional): Número máximo de resultados a devolver (predeterminado: 5, máximo: 20)
    • search_depth (cadena, opcional): Profundidad de búsqueda "básica" o "avanzada" (predeterminado: "básica")
    • include_domains (lista o cadena, opcional): Lista de dominios a incluir específicamente en los resultados
    • exclude_domains (lista o cadena, opcional): Lista de dominios a excluir de los resultados

  • tavily_answer_search - Realiza búsquedas web y genera respuestas directas con evidencia de respaldo.

    • query (cadena, obligatorio): Consulta de búsqueda
    • max_results (entero, opcional): Número máximo de resultados a devolver (predeterminado: 5, máximo: 20)
    • search_depth (cadena, opcional): Profundidad de búsqueda "básica" o "avanzada" (predeterminado: "avanzada")
    • include_domains (lista o cadena, opcional): Lista de dominios a incluir específicamente en los resultados
    • exclude_domains (lista o cadena, opcional): Lista de dominios a excluir de los resultados

  • tavily_news_search - Busca artículos de noticias recientes con fechas de publicación.

    • query (cadena, obligatorio): Consulta de búsqueda
    • max_results (entero, opcional): Número máximo de resultados a devolver (predeterminado: 5, máximo: 20)
    • days (entero, opcional): Número de días hacia atrás para buscar (predeterminado: 3)
    • include_domains (lista o cadena, opcional): Lista de dominios a incluir específicamente en los resultados
    • exclude_domains (lista o cadena, opcional): Lista de dominios a excluir de los resultados

Prompts

El servidor también proporciona plantillas de prompts para cada tipo de búsqueda:

  • tavily_web_search - Busca en la web usando el motor de búsqueda impulsado por IA de Tavily
  • tavily_answer_search - Busca en la web y obtén una respuesta generada por IA con evidencia de respaldo
  • tavily_news_search - Busca artículos de noticias recientes con la búsqueda de noticias de Tavily

Requisitos previos

  • Python 3.11 o posterior
  • Una clave de API de Tavily (obtenerla en el sitio web de Tavily)
  • uv administrador de paquetes de Python (recomendado)

Instalación

Opción 1: Usando pip o uv

# With pip
pip install mcp-tavily

# Or with uv (recommended)
uv add mcp-tavily

Deberías ver una salida similar a:

Resolved packages: mcp-tavily, mcp, pydantic, python-dotenv, tavily-python [...]
Successfully installed mcp-tavily-0.1.4 mcp-1.0.0 [...]

Opción 2: Desde el código fuente

# Clone the repository
git clone https://github.com/RamXX/mcp-tavily.git
cd mcp-tavily

# Create a virtual environment (optional but recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies and build
uv sync  # Or: pip install -r requirements.txt
uv build  # Or: pip install -e .

# To install with test dependencies:
uv sync --dev  # Or: pip install -r requirements-dev.txt

Durante la instalación, deberías ver el paquete compilándose e instalándose con sus dependencias.

Uso con VS Code

Para una instalación rápida, usa uno de los botones de instalación con un clic a continuación:

Install with UV in VS Code Install with UV in VS Code Insiders

Para instalación manual, agrega el siguiente bloque JSON a tu archivo de Configuración de Usuario (JSON) en VS Code. Puedes hacer esto presionando Ctrl + Shift + P y escribiendo Preferences: Open User Settings (JSON).

Opcionalmente, puedes agregarlo a un archivo llamado .vscode/mcp.json en tu espacio de trabajo. Esto te permitirá compartir la configuración con otros.

Ten en cuenta que la clave mcp no es necesaria en el archivo .vscode/mcp.json.

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "apiKey",
        "description": "Tavily API Key",
        "password": true
      }
    ],
    "servers": {
      "tavily": {
        "command": "uvx",
        "args": ["mcp-tavily"],
        "env": {
          "TAVILY_API_KEY": "${input:apiKey}"
        }
      }
    }
  }
}

Configuración

Configuración de la clave de API

El servidor requiere una clave de API de Tavily, que se puede proporcionar de tres maneras:

  1. A través de un archivo .env en el directorio de tu proyecto:

    TAVILY_API_KEY=your_api_key_here

  2. Como variable de entorno:

    export TAVILY_API_KEY=your_api_key_here

  3. Como argumento de línea de comandos:

    python -m mcp_server_tavily --api-key=your_api_key_here

Configurar para Claude.app

Agrega a la configuración de Claude:

"mcpServers": {
  "tavily": {
    "command": "python",
    "args": ["-m", "mcp_server_tavily"]
  },
  "env": {
    "TAVILY_API_KEY": "your_api_key_here"
  }
}

Si encuentras problemas, es posible que debas especificar la ruta completa a tu intérprete de Python. Ejecuta which python para encontrar la ruta exacta.

Ejemplos de uso

Para una búsqueda web regular:

Tell me about Anthropic's newly released MCP protocol

Para generar un informe con filtrado de dominios:

Tell me about redwood trees. Please use MLA format in markdown syntax and include the URLs in the citations. Exclude Wikipedia sources.

Para usar el modo de búsqueda de respuestas para respuestas directas:

I want a concrete answer backed by current web sources: What is the average lifespan of redwood trees?

Para búsqueda de noticias:

Give me the top 10 AI-related news in the last 5 days

Pruebas

El proyecto incluye un conjunto completo de pruebas con pruebas automatizadas de compatibilidad de dependencias.

Ejecutar pruebas

  1. Instala las dependencias de prueba:

    source .venv/bin/activate  # If using a virtual environment
uv sync --dev  # Or: pip install -r requirements-dev.txt

  2. Ejecuta el conjunto de pruebas estándar:

    ./tests/run_tests.sh
# Or using Make
make test

Pruebas de compatibilidad de dependencias

Para asegurar que el proyecto funcione con las últimas versiones de dependencias, usa estos comandos:

# Test with latest dependencies using Make
make test-deps

# Full compatibility test with verbose output
make test-compatibility

# Or use the standalone script
./scripts/test-compatibility.sh

Estos comandos:

  • Actualizarán todas las dependencias a sus últimas versiones
  • Ejecutarán el conjunto completo de pruebas con cobertura
  • Informarán cualquier problema de compatibilidad
  • Mostrarán los cambios de versión para transparencia

Pruebas automatizadas

El proyecto incluye pruebas automatizadas de compatibilidad de dependencias a través de GitHub Actions:

  • Pruebas semanales: Se ejecutan cada lunes a las 8 AM UTC
  • Soporte multi-Python: Pruebas contra Python 3.11, 3.12 y 3.13
  • Creación de issues: Crea automáticamente issues de GitHub cuando fallan las pruebas
  • Activación manual: Se puede activar manualmente desde la pestaña de GitHub Actions

Comprender los resultados de las pruebas

Cuando las pruebas pasan: Tu proyecto es compatible con las últimas versiones de dependencias. Puedes actualizar tus archivos de requisitos de manera segura.

Cuando las pruebas fallan: Revisa la salida de las pruebas para identificar cambios importantes, actualiza tu código para manejar cambios de API, actualiza las pruebas si es necesario, o considera fijar versiones problemáticas de dependencias.

Ejemplo de salida de prueba

Deberías ver una salida similar a:

======================================================= test session starts ========================================================
platform darwin -- Python 3.13.3, pytest-8.3.5, pluggy-1.5.0
rootdir: /Users/ramirosalas/workspace/mcp-tavily
configfile: pyproject.toml
plugins: cov-6.0.0, asyncio-0.25.3, anyio-4.8.0, mock-3.14.0
asyncio: mode=Mode.STRICT, asyncio_default_fixture_loop_scope=function
collected 50 items                                                                                                                 

tests/test_docker.py ..                                                                                                      [  4%]
tests/test_integration.py .....                                                                                              [ 14%]
tests/test_models.py .................                                                                                       [ 48%]
tests/test_server_api.py .....................                                                                               [ 90%]
tests/test_utils.py .....                                                                                                    [100%]

---------- coverage: platform darwin, python 3.13.3-final-0 ----------
Name                                Stmts   Miss  Cover
-------------------------------------------------------
src/mcp_server_tavily/__init__.py      16      2    88%
src/mcp_server_tavily/__main__.py       2      2     0%
src/mcp_server_tavily/server.py       149     16    89%
-------------------------------------------------------
TOTAL                                 167     20    88%

El conjunto de pruebas incluye pruebas para modelos de datos, funciones de utilidad, pruebas de integración, manejo de errores y validación de parámetros. Se enfoca en verificar que todas las capacidades de la API funcionen correctamente, incluido el manejo de filtros de dominios y varios formatos de entrada.

Gestión de versiones

El proyecto incluye herramientas para compilar y publicar con las últimas versiones de dependencias:

Compilar con las últimas dependencias

# Build package with latest dependency versions
make build-latest

# Complete release workflow: test, build, and check with latest deps
make release-all

# Prepare a release with version management
./scripts/prepare-release.sh [new_version]

Flujo de trabajo de publicación

Enfoque recomendado para publicaciones con las últimas dependencias:

  1. Completar la preparación de la publicación: make release-all
  2. Subir sin degradaciones: make upload-latest

Enfoque alternativo paso a paso:

  1. Probar con las últimas dependencias: make test-compatibility
  2. Compilar para publicación: make release-build
  3. Subir sin recompilar: make upload-latest

Publicación y lanzamiento con un solo comando:

make release-publish

Importante: Usa make upload-latest en lugar de make upload para evitar degradaciones de dependencias durante el proceso de subida. El comando upload-latest usa archivos de distribución existentes sin reinstalar dependencias.

Los comandos de publicación aseguran que tu paquete se compile y pruebe con las versiones de dependencias compatibles más recientes, evitando las degradaciones que pueden ocurrir con cadenas de compilación tradicionales.

Docker

Compila la imagen de Docker:

make docker-build

Alternativamente, compila directamente con Docker:

docker build -t mcp_tavily .

Ejecuta un contenedor de Docker en segundo plano (nombre predeterminado mcp_tavily_container, puerto 8000 → 8000):

make docker-run

O manualmente:

docker run -d --name mcp_tavily_container \
  -e TAVILY_API_KEY=your_api_key_here \
  -p 8000:8000 mcp_tavily

Detén y elimina el contenedor:

make docker-stop

Sigue los registros del contenedor:

make docker-logs

Puedes anular los valores predeterminados configurando variables de entorno:

  • DOCKER_IMAGE: nombre de la imagen (predeterminado mcp_tavily)
  • DOCKER_CONTAINER: nombre del contenedor (predeterminado mcp_tavily_container)
  • HOST_PORT: puerto del host a vincular (predeterminado 8000)
  • CONTAINER_PORT: puerto del contenedor (predeterminado 8000)

Depuración

Puedes usar el inspector de MCP para depurar el servidor:

# Using npx
npx @modelcontextprotocol/inspector python -m mcp_server_tavily

# For development
cd path/to/mcp-tavily
npx @modelcontextprotocol/inspector python -m mcp_server_tavily

Contribuciones

¡Damos la bienvenida a contribuciones para mejorar mcp-tavily! Así es como puedes ayudar:

  1. Haz un fork del repositorio
  2. Crea una rama de características (git checkout -b feature/amazing-feature)
  3. Realiza tus cambios
  4. Ejecuta las pruebas para asegurarte de que pasen
  5. Confirma tus cambios (git commit -m 'Add amazing feature')
  6. Sube a la rama (git push origin feature/amazing-feature)
  7. Abre una Solicitud de Extracción

Para ejemplos de otros servidores MCP y patrones de implementación, consulta: https://github.com/modelcontextprotocol/servers

Licencia

mcp-tavily está licenciado bajo la Licencia MIT. Consulta el archivo LICENCIA para más detalles.