🎯 MCP Hunter

Servidor MCP (Model Context Protocol) para OSINT, Prospecção Ativa, Busca Web, Scraping Profundo e Enriquecimento de Dados de Empresas e Pessoas.

O MCP Hunter conecta assistentes de inteligência artificial (como Gemini Antigravity, Claude Desktop, Cursor e Windsurf) diretamente à internet e a fontes de dados abertas. Ele é capaz de pesquisar no Google/Web, raspar e limpar páginas de forma inteligente, extrair contatos (e-mails, WhatsApp, telefones, redes sociais) e enriquecer perfis de empresas com dados oficiais da Receita Federal (CNPJ, Sócios/QSA, Capital Social e Endereço).

✨ Principais Funcionalidades

• 🔍 Busca na Web sem Chaves Pagas: Pesquisa rápida com suporte a operadores avançados (site:, inurl:, filetype:) e foco regional no Brasil (br-pt).

• 🌐 Scraping e Limpeza Inteligente de Conteúdo: Utiliza trafilatura e BeautifulSoup para extrair somente o texto principal, eliminando anúncios, menus e códigos.

• 📞 Extrator Cirúrgico de Contatos: Algoritmos de Regex e heurísticas para identificar:

  • E-mails válidos (com filtro anti-lixo e anti-imagens);

  • Telefones fixos e celulares no padrão brasileiro;

  • Links diretos de WhatsApp (wa.me/ e api.whatsapp.com);

  • Perfis oficiais em redes sociais (Instagram, LinkedIn, Facebook, X/Twitter, YouTube, TikTok, GitHub);

  • Números de CNPJ com validação matemática dos dígitos verificadores.

• 🏛️ Consulta Oficial à Receita Federal (BrasilAPI): Obtém Razão Social, Nome Fantasia, Situação Cadastral, Data de Abertura, Capital Social, Atividade Principal (CNAE), Endereço e Quadro de Sócios e Administradores (QSA).

• 🏢 Modo Mestre (hunt_company): Recebe o nome de uma empresa e executa a investigação 360º de ponta a ponta em segundos.

• 👤 Investigação de Pessoas (hunt_person): Varre menções públicas, perfis no LinkedIn e artigos sobre uma pessoa.

Related MCP server: LeadSpark MCP

🛠️ Ferramentas (Tools) Expostas

🚀 Instalação e Execução

Este projeto utiliza o gerenciador de pacotes ultra-rápido uv.

1. Clonar o repositório

git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"

2. Instalar dependências automaticamente

uv sync

3. Executar os testes automatizados

uv run python tests/test_tools.py

4. Iniciar o servidor MCP (modo stdio)

uv run mcp-hunter

🔌 Configuração nos Clientes MCP

Antigravity / Claude Desktop / Cursor / Windsurf

Adicione a configuração abaixo no seu arquivo de configuração MCP (claude_desktop_config.json ou similar):

{
  "mcpServers": {
    "mcp-hunter": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\caminho\\para\\MCP Hunter",
        "run",
        "mcp-hunter"
      ]
    }
  }
}

📂 Estrutura do Projeto

MCP Hunter/
├── src/
│   └── mcp_hunter/
│       ├── __init__.py        # Definição do pacote
│       ├── server.py          # Servidor FastMCP e registro das Tools
│       ├── search.py          # Motor de buscas na Web (DuckDuckGo/DDGS)
│       ├── scraper.py         # Motor de requisições HTTP e scraping (Trafilatura/BS4)
│       ├── extractor.py       # Extração de contatos, regex e validação de CNPJ
│       ├── cnpj.py            # Integração com BrasilAPI e Receita Federal
│       └── py.typed           # Marcador de tipagem PEP 561
├── tests/
│   ├── test_hunter.py         # Testes unitários dos módulos internos
│   └── test_tools.py          # Testes de integração das ferramentas MCP
├── mcp_config_example.json    # Exemplo de configuração de cliente MCP
├── pyproject.toml             # Configuração do projeto e dependências
├── uv.lock                    # Lockfile de dependências
└── README.md                  # Documentação oficial

📄 Licença

Distribuído sob a licença MIT. Consulte LICENSE para obter mais informações.