web-search-mcp

Um servidor de pesquisa (MCP) abrangente e pronto para produção. Forneça aos seus clientes LLM acesso em tempo real à web, dados e muito mais.

GitHub

Experimente este MCPPatrocinado

Documentação

Web Search MCP

Um servidor abrangente de Model Context Protocol (MCP) construído com FastMCP que fornece aos LLMs acesso em tempo real e de alta fidelidade à web. Este servidor agrega múltiplos mecanismos de busca, plataformas sociais e ferramentas de desenvolvedor em uma única interface, permitindo que agentes de IA realizem pesquisas aprofundadas, acompanhem o sentimento da comunidade e analisem documentação técnica.

Documentos de design → wiki — guia de seleção de ferramentas, matriz de decisão, fluxos de trabalho recomendados, status das ferramentas e peculiaridades conhecidas, configuração de plugins e padrões de desenvolvimento.

🚀 Recursos

O servidor fornece um conjunto diversificado de ferramentas categorizadas pelo seu caso de uso principal:

🌐 Busca Geral na Web e Recuperação

Ferramenta	Descrição	Melhor Para
`search_web`	Busca rápida na web via DuckDuckGo ou Exa (SDK). Suporta escopo por domínio, filtro por data, modo de notícias e região geográfica. O provedor automático padrão tenta DDG primeiro e recorre ao Exa.	Consultas rápidas, buscas de alto volume, paginação, cobertura ampla
`fetch_page`	Extração de texto de alta fidelidade de URLs com bypass de detecção de bots, proteção SSRF (bloqueia IPs privados/internos) e múltiplos formatos de saída.	Leitura aprofundada de resultados de busca, busca de URLs independentes

💬 Inteligência Social e Comunitária

Ferramenta	Descrição	Melhor Para
`search_reddit`	Busca sem chave para discussões comunitárias, opiniões e experiências reais de usuários via RSS + enriquecimento Shreddit.	Avaliações de produtos, sentimento comunitário, solução de problemas
`search_hackernews`	Discursos técnicos, notícias de startups e opiniões de desenvolvedores via API Algolia HN.	Notícias de tecnologia, discussões de startups, opiniões de desenvolvedores
`search_github`	Busca por Issues e PRs para rastrear bugs, solicitações de recursos e sentimento comunitário. Requer CLI `gh` ou `GITHUB_TOKEN`.	Rastreamento de bugs, solicitações de recursos, sentimento comunitário
`get_github_issue`	Busca de threads de conversa completos de Issues/PRs do GitHub, ordenados por reações com metadados de autor/data/reações.	Aprofundamento em issues/PRs específicos
`search_x`	Discurso em tempo real e notícias de última hora via API Xquik ou CLI Bird incorporada (requer cookies de sessão ou chave de API).	Notícias de última hora, reações comunitárias, sinais de engajamento
`search_linkedin`	Busca de pessoas, empresas, empregos, posts via DuckDuckGo + Jina Reader (r.jina.ai). Nenhuma chave de API necessária.	Perfis profissionais, pesquisa de empresas, busca de empregos

🎓 Acadêmico e Referência

Ferramenta	Descrição	Melhor Para
`search_arxiv`	Busca especializada para artigos acadêmicos com prefixos de campo Lucene (`au:`, `ti:`, `cat:`, `abs:`).	Artigos de pesquisa, citações, revisões de literatura
`search_wikipedia`	Resumos factuais e pesquisa de contexto via API MediaWiki.	Resumos factuais, pesquisa de contexto, citações

📋 Pré-requisitos

Requisito	Versão	Notas
Python	3.11+	Obrigatório
uv	Mais recente	Recomendado para instalação e gerenciamento de ambiente

Ferramentas Externas Opcionais

Ferramenta	Necessária Para	Instalação
CLI `gh`	Busca autenticada no GitHub e recuperação de issues (limites de taxa mais altos)	`brew install gh` / github.com/cli/cli
Node.js	CLI Bird incorporada para busca no X/Twitter (não necessária com `XQUIK_API_KEY`)	22+ recomendado; `brew install node@22` / nodejs.org

⚙️ Instalação

Você tem três opções dependendo do seu caso de uso:

Opção A: Execução Rápida (via `uvx`)

A maneira mais rápida de experimentar sem clonar o repositório. Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "Web-Research": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sydasif/web-search-mcp.git",
        "web-search-mcp"
      ]
    }
  }
}

Opção B: Instalação Permanente

Tempos de inicialização mais rápidos com uma ferramenta instalada globalmente:

uv tool install git+https://github.com/sydasif/web-search-mcp.git

Em seguida, configure seu cliente MCP:

{
  "mcpServers": {
    "Web-Research": {
      "command": "web-search-mcp"
    }
  }
}

Opção C: Instalação para Desenvolvimento

Se você quiser modificar o código ou contribuir:

git clone https://github.com/sydasif/web-search-mcp.git
cd web-search-mcp
uv sync
uv run web-search-mcp

Verifique se Está Funcionando

Quando o servidor estiver em execução, tente uma busca simples:

search_web(query="current weather in Tokyo")

🔐 Configuração e Autenticação

A maioria das ferramentas funciona prontas para uso sem configuração. As seguintes variáveis de ambiente são necessárias apenas para recursos premium ou autenticados.

Referência de Variáveis de Ambiente

Variável	Necessária Para	Como Obter
`EXA_API_KEY`	Busca semântica Exa AI (fallback opcional)	Cadastre-se em exa.ai
`GITHUB_TOKEN`	Limites de taxa mais altos da API do GitHub (opcional)	Gere um GitHub PAT
`AUTH_TOKEN`	Busca no X/Twitter via CLI Bird (obrigatório)	Cookie de sessão de x.com (veja abaixo)
`CT0`	Busca no X/Twitter via CLI Bird (obrigatório)	Cookie de sessão de x.com (veja abaixo)
`XQUIK_API_KEY`	Busca no X/Twitter via API Xquik (alternativa aos cookies)	Cadastre-se em xquik.ai

Configurando Autenticação do GitHub

Opção 1 — Recomendada: Use a CLI gh

gh auth login

O servidor detecta sua sessão local automaticamente.

Opção 2: Token Manual

export GITHUB_TOKEN="ghp_your_token_here"

Configurando Autenticação do X/Twitter

A busca no X/Twitter requer cookies de sessão ou uma chave de API.

Opção 1 — Cookies de Sessão (CLI Bird):

Faça login em x.com no seu navegador.
Abra o DevTools (F12) → Application (ou Storage) → Cookies → x.com.
Copie os valores de auth_token e ct0.
Exporte-os no shell onde o servidor MCP é executado:
```
export AUTH_TOKEN="your_auth_token"
export CT0="your_ct0"
```
Nota: Estes são cookies de sessão. Se as buscas retornarem 401, atualize-os fazendo logout e login novamente.

Opção 2 — Chave de API Xquik (Recomendada):

Cadastre-se em xquik.ai para obter uma chave de API.
Exporte-a:
```
export XQUIK_API_KEY="your_xquik_key"
```
Isso elimina completamente a dependência da CLI Bird do Node.js.

Configurando Exa AI (Opcional)

O Exa fornece busca semântica e fallback para páginas com muito JavaScript:

export EXA_API_KEY="your_exa_key"

💡 Exemplos de Uso

Pesquisa na Web

# Broad search (auto: DDG first, falls back to Exa on error or zero results)
search_web(query="Latest NVIDIA H200 benchmarks")

# Force DDG explicitly
search_web(query="uv package manager", provider="ddg")

# Force Exa explicitly
search_web(query="uv package manager", provider="exa")

# Targeted documentation search
search_web(query="useEffect cleanup", domain="react.dev")

# News with region filter
search_web(query="elections", search_type="news", region="us-en", provider="exa")

# Date-filtered search
search_web(query="uv package manager", time_range="w", provider="auto")

# Deep read a page
fetch_page(url="https://docs.python.org/3/library/os.html")

Análise Técnica

# Track GitHub issues/PRs
search_github(query="uv package manager")

# Get full GitHub issue thread
get_github_issue(url="https://github.com/astral-sh/uv/issues/1")

Sentimento Comunitário

# Reddit discussions
search_reddit(query="Best mechanical keyboards 2024", subreddits=["MechanicalKeyboards"])

# Hacker News technical discourse
search_hackernews(query="MCP server architecture")

# LinkedIn professional search
search_linkedin(query="site reliability engineer", content_type="people")
search_linkedin(query="machine learning startup", content_type="companies")
search_linkedin(query="kubernetes devops", content_type="jobs")
search_linkedin(query="AI agents", content_type="posts")

Pesquisa Acadêmica

# arXiv paper search with field prefixes
search_arxiv(query="au:Goodfellow AND cat:cs.LG")
search_arxiv(query="transformer attention", sort_by="submitted_date")

# Wikipedia background research
search_wikipedia(query="Quantum computing")

🏗️ Estrutura do Projeto

web_search_mcp/
├── server.py              # Entry point: FastMCP init, @mcp.tool registrations
├── search/                # Search engine implementations
│   ├── ddg.py             # DuckDuckGo search + trafilatura page fetch
│   └── exa.py             # Exa SDK search & content fetch (lazy-init client)
├── social/                # Community platform integrations
│   ├── github.py          # GitHub Search API + gh CLI issue rendering
│   ├── hackernews.py      # Algolia HN API + comment enrichment
│   ├── linkedin/          # LinkedIn search via DDG + Jina Reader
│   │   ├── __init__.py    # LinkedIn search tool registration
│   │   └── client.py      # DDG search + Jina Reader enrichment
│   ├── reddit/            # RSS + Shreddit keyless pipeline
│   │   ├── client.py      # HTTP client with RSS parsing
│   │   ├── parsers.py     # RSS/HTML parsers
│   │   └── shreddit.py    # Shreddit comment enrichment
│   └── x.py               # X/Twitter search via Xquik API or vendored Bird CLI
├── tools/                 # Specialized reference utilities
│   ├── arxiv.py           # arXiv paper search (Lucene field prefixes)
│   └── wikipedia.py       # Wikipedia MediaWiki API
├── _config/               # Settings, env vars, rate limits, depth tiers
│   ├── settings.py        # pydantic-settings (EXA_API_KEY, SEARCH_MCP_ prefix)
│   └── limits.py          # Per-platform quick/default/deep limits, timeouts
├── _http/                 # Shared HTTP + SSRF protection
│   └── client.py          # validate_url, http_client, get_json_client
├── _models/               # Pydantic request/response models
│   ├── requests.py        # SearchRequest
│   ├── responses.py       # ErrorResponse, SearchResponse, PageResponse
│   └── types.py           # Depth, ResponseFormat, SearchType, FetchOutputFormat
├── _utils/                # Shared helpers
│   ├── formatting.py      # Markdown formatters, date/epoch utils
│   ├── rate_limiter.py    # Token-bucket rate limiter
│   └── scoring.py         # Relevance scoring
└── vendor/                # Vendored third-party tools
    └── bird-search/       # Node.js CLI for X/Twitter search (fallback when XQUIK_API_KEY unset)

🛠️ Fluxo de Implementação de Ferramentas

Ao adicionar uma nova ferramenta:

Implemente a lógica no módulo apropriado (search/, social/ ou tools/)
Defina os modelos em _models/ (tipos de requisição/resposta)
Registre em server.py usando o decorador @mcp.tool com um docstring claro (serve como descrição da ferramenta para o LLM)

📐 Decisões de Design

search-backend-split — Por que search_web unifica DuckDuckGo e Exa atrás de um único parâmetro provider em vez de expor duas ferramentas separadas.

🧪 Testes

# Run all tests
uv run pytest

# Run a single test file
uv run pytest tests/test_module.py

# Run a specific test
uv run pytest tests/test_module.py::test_function_name

# Run with coverage
uv run pytest --cov=web_search_mcp

🔧 Solução de Problemas

Problema	Causa Provável	Solução
Erros de autenticação em uma ferramenta	Variável de ambiente não definida no shell do servidor	Exporte a variável no mesmo shell onde o processo do servidor MCP é executado
GitHub retorna resultados vazios	Não autenticado	Execute `gh auth login` ou defina `GITHUB_TOKEN`
`search_x` retorna 401	Cookies de sessão X expirados	Re-extraia `auth_token` e `ct0` de x.com
`fetch_page` bloqueado pelo Cloudflare	Detecção de bots	Tente o parâmetro `backend="curl"`
`search_arxiv` retorna 503	Manutenção upstream do arXiv	Aguarde alguns minutos e tente novamente
Ferramenta diz "Query cannot be empty"	Consulta ausente ou em branco	Forneça uma consulta de busca não vazia

🤝 Contribuindo

Faça um fork do repositório.
Crie um branch de recurso: git checkout -b feat/my-new-tool
Garanta que todos os testes passem: uv run pytest
Envie um pull request com uma descrição detalhada das alterações.

📄 Licença

Este projeto está licenciado sob a Licença MIT.