Tavily Search

Pesquisa na web com tecnologia de IA usando a API Tavily Search.

Documentação

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

Aviso de descontinuação

Construí este servidor MCP no início de março de 2025, quando o protocolo MCP era totalmente novo e não havia maneiras consistentes de fazer buscas em chatbots, antecedendo outras implementações.

Desde então, o pessoal da Tavily lançou seu servidor MCP oficial da Tavily, que é bem mantido e está em sintonia com seus recursos mais recentes. Portanto, estou descontinuando este servidor em favor do deles.

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

Tavily MCP Server

Um servidor Model Context Protocol que fornece recursos de busca na web com IA usando a API de busca da Tavily. Este servidor permite que LLMs realizem buscas sofisticadas na web, obtenham respostas diretas a perguntas e pesquisem artigos de notícias recentes com conteúdo relevante extraído por IA.

Recursos

Ferramentas Disponíveis

tavily_web_search - Realiza buscas abrangentes na web com extração de conteúdo alimentada por IA.
- query (string, obrigatório): Consulta de busca
- max_results (inteiro, opcional): Número máximo de resultados a retornar (padrão: 5, máximo: 20)
- search_depth (string, opcional): Profundidade de busca "basic" ou "advanced" (padrão: "basic")
- include_domains (lista ou string, opcional): Lista de domínios a incluir especificamente nos resultados
- exclude_domains (lista ou string, opcional): Lista de domínios a excluir dos resultados
tavily_answer_search - Realiza buscas na web e gera respostas diretas com evidências de apoio.
- query (string, obrigatório): Consulta de busca
- max_results (inteiro, opcional): Número máximo de resultados a retornar (padrão: 5, máximo: 20)
- search_depth (string, opcional): Profundidade de busca "basic" ou "advanced" (padrão: "advanced")
- include_domains (lista ou string, opcional): Lista de domínios a incluir especificamente nos resultados
- exclude_domains (lista ou string, opcional): Lista de domínios a excluir dos resultados
tavily_news_search - Pesquisa artigos de notícias recentes com datas de publicação.
- query (string, obrigatório): Consulta de busca
- max_results (inteiro, opcional): Número máximo de resultados a retornar (padrão: 5, máximo: 20)
- days (inteiro, opcional): Número de dias retroativos para busca (padrão: 3)
- include_domains (lista ou string, opcional): Lista de domínios a incluir especificamente nos resultados
- exclude_domains (lista ou string, opcional): Lista de domínios a excluir dos resultados

Prompts

O servidor também fornece modelos de prompt para cada tipo de busca:

tavily_web_search - Busque na web usando o mecanismo de busca com IA da Tavily
tavily_answer_search - Busque na web e obtenha uma resposta gerada por IA com evidências de apoio
tavily_news_search - Pesquise artigos de notícias recentes com a busca de notícias da Tavily

Pré-requisitos

Python 3.11 ou posterior
Uma chave de API da Tavily (obtenha no site da Tavily)
uv gerenciador de pacotes Python (recomendado)

Instalação

Opção 1: Usando pip ou uv

# With pip
pip install mcp-tavily

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

Você deve ver uma saída semelhante a:

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

Opção 2: A partir do código-fonte

# 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 a instalação, você deve ver o pacote sendo compilado e instalado com suas dependências.

Uso com VS Code

Para instalação rápida, use um dos botões de instalação com um clique abaixo:

Para instalação manual, adicione o seguinte bloco JSON ao arquivo User Settings (JSON) no VS Code. Você pode fazer isso pressionando Ctrl + Shift + P e digitando Preferences: Open User Settings (JSON).

Opcionalmente, você pode adicioná-lo a um arquivo chamado .vscode/mcp.json no seu workspace. Isso permitirá compartilhar a configuração com outras pessoas.

Observe que a chave mcp não é necessária no arquivo .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}"
        }
      }
    }
  }
}

Configuração

Configuração da Chave de API

O servidor requer uma chave de API da Tavily, que pode ser fornecida de três maneiras:

Por meio de um arquivo .env no diretório do seu projeto:
```
TAVILY_API_KEY=your_api_key_here
```

Como variável de ambiente:

export TAVILY_API_KEY=your_api_key_here

Como argumento de linha de comando:

python -m mcp_server_tavily --api-key=your_api_key_here

Configurar para Claude.app

Adicione às suas configurações do Claude:

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

Se você encontrar problemas, talvez seja necessário especificar o caminho completo para o seu interpretador Python. Execute which python para encontrar o caminho exato.

Exemplos de Uso

Para uma busca web regular:

Tell me about Anthropic's newly released MCP protocol

Para gerar um relatório com filtragem de domínio:

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

Para usar o modo de busca de respostas para respostas diretas:

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

Para busca de notícias:

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

Testes

O projeto inclui uma suíte de testes abrangente com testes automatizados de compatibilidade de dependências.

Executando Testes

Instale as dependências de teste:

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

Execute a suíte de testes padrão:

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

Teste de Compatibilidade de Dependências

Para garantir que o projeto funcione com as versões mais recentes das dependências, use estes 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

Estes comandos irão:

Atualizar todas as dependências para suas versões mais recentes
Executar a suíte de testes completa com cobertura
Relatar quaisquer problemas de compatibilidade
Mostrar alterações de versão para transparência

Testes Automatizados

O projeto inclui testes automatizados de compatibilidade de dependências por meio do GitHub Actions:

Testes Semanais: Executados toda segunda-feira às 8h UTC
Suporte Multi-Python: Testes com Python 3.11, 3.12 e 3.13
Criação de Issues: Cria automaticamente issues no GitHub quando os testes falham
Acionamento Manual: Pode ser acionado manualmente na aba GitHub Actions

Entendendo os Resultados dos Testes

Quando os testes passam: Seu projeto é compatível com as versões mais recentes das dependências. Você pode atualizar com segurança seus arquivos de requisitos.

Quando os testes falham: Revise a saída dos testes para identificar mudanças que quebram a compatibilidade, atualize seu código para lidar com alterações de API, atualize os testes se necessário ou considere fixar versões problemáticas de dependências.

Exemplo de Saída de Teste

Você deve ver uma saída semelhante 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%

A suíte de testes inclui testes para modelos de dados, funções utilitárias, testes de integração, tratamento de erros e validação de parâmetros. Ela se concentra em verificar se todos os recursos da API funcionam corretamente, incluindo o tratamento de filtros de domínio e vários formatos de entrada.

Gerenciamento de Lançamentos

O projeto inclui ferramentas para compilar e lançar com as versões mais recentes das dependências:

Compilando com Dependências Mais Recentes

# 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]

Fluxo de Trabalho de Lançamento

Abordagem recomendada para lançamentos com dependências mais recentes:

Conclua a preparação do lançamento: make release-all
Envie sem rebaixamentos: make upload-latest

Abordagem alternativa passo a passo:

Teste com dependências mais recentes: make test-compatibility
Compile para lançamento: make release-build
Envie sem recompilar: make upload-latest

Lançamento e publicação com um comando:

make release-publish

Importante: Use make upload-latest em vez de make upload para evitar rebaixamentos de dependências durante o processo de envio. O comando upload-latest usa arquivos de distribuição existentes sem reinstalar dependências.

Os comandos de lançamento garantem que seu pacote seja compilado e testado com as versões de dependências compatíveis mais recentes, prevenindo os rebaixamentos que podem ocorrer com cadeias de compilação tradicionais.

Docker

Compile a imagem Docker:

make docker-build

Alternativamente, compile diretamente com Docker:

docker build -t mcp_tavily .

Execute um contêiner Docker em segundo plano (nome padrão mcp_tavily_container, porta 8000 → 8000):

make docker-run

Ou manualmente:

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

Pare e remova o contêiner:

make docker-stop

Acompanhe os logs do contêiner:

make docker-logs

Você pode substituir os padrões definindo variáveis de ambiente:

DOCKER_IMAGE: nome da imagem (padrão mcp_tavily)
DOCKER_CONTAINER: nome do contêiner (padrão mcp_tavily_container)
HOST_PORT: porta do host para vincular (padrão 8000)
CONTAINER_PORT: porta do contêiner (padrão 8000)

Depuração

Você pode usar o inspetor MCP para depurar o 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

Contribuindo

Aceitamos contribuições para melhorar o mcp-tavily! Veja como você pode ajudar:

Faça um fork do repositório
Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
Faça suas alterações
Execute os testes para garantir que passem
Faça commit das suas alterações (git commit -m 'Add amazing feature')
Envie para o branch (git push origin feature/amazing-feature)
Abra um Pull Request

Para exemplos de outros servidores MCP e padrões de implementação, consulte: https://github.com/modelcontextprotocol/servers

Licença

O mcp-tavily é licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.