🎯 MCP Hunter

Servidor MCP (Model Context Protocol) para OSINT, Prospección Activa, Búsqueda Web, Scraping Profundo y Enriquecimiento de Datos de Empresas y Personas.

El MCP Hunter conecta asistentes de inteligencia artificial (como Gemini Antigravity, Claude Desktop, Cursor y Windsurf) directamente a internet y a fuentes de datos abiertas. Es capaz de buscar en Google/Web, raspar y limpiar páginas de forma inteligente, extraer contactos (correos electrónicos, WhatsApp, teléfonos, redes sociales) y enriquecer perfiles de empresas con datos oficiales de la Receita Federal (CNPJ, Socios/QSA, Capital Social y Dirección).

✨ Principales Funcionalidades

• 🔍 Búsqueda en la Web sin Claves de Pago: Búsqueda rápida con soporte para operadores avanzados (site:, inurl:, filetype:) y enfoque regional en Brasil (br-pt).

• 🌐 Scraping y Limpieza Inteligente de Contenido: Utiliza trafilatura y BeautifulSoup para extraer solo el texto principal, eliminando anuncios, menús y códigos.

• 📞 Extractor Quirúrgico de Contactos: Algoritmos de Regex y heurísticas para identificar:

  • Correos electrónicos válidos (con filtro anti-spam y anti-imágenes);

  • Teléfonos fijos y móviles en el estándar brasileño;

  • Enlaces directos de WhatsApp (wa.me/ y api.whatsapp.com);

  • Perfiles oficiales en redes sociales (Instagram, LinkedIn, Facebook, X/Twitter, YouTube, TikTok, GitHub);

  • Números de CNPJ con validación matemática de los dígitos verificadores.

• 🏛️ Consulta Oficial a la Receita Federal (BrasilAPI): Obtiene Razón Social, Nombre Comercial, Situación Registral, Fecha de Apertura, Capital Social, Actividad Principal (CNAE), Dirección y Cuadro de Socios y Administradores (QSA).

• 🏢 Modo Maestro (hunt_company): Recibe el nombre de una empresa y ejecuta la investigación 360º de principio a fin en segundos.

• 👤 Investigación de Personas (hunt_person): Escanea menciones públicas, perfiles en LinkedIn y artículos sobre una persona.

Related MCP server: LeadSpark MCP

🛠️ Herramientas (Tools) Expuestas

🚀 Instalación y Ejecución

Este proyecto utiliza el gestor de paquetes ultrarrápido uv.

1. Clonar el repositorio

git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"

2. Instalar dependencias automáticamente

uv sync

3. Ejecutar las pruebas automatizadas

uv run python tests/test_tools.py

4. Iniciar el servidor MCP (modo stdio)

uv run mcp-hunter

🔌 Configuración en los Clientes MCP

Antigravity / Claude Desktop / Cursor / Windsurf

Añade la configuración siguiente en tu archivo de configuración MCP (claude_desktop_config.json o similar):

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

📂 Estructura del Proyecto

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

📄 Licencia

Distribuido bajo la licencia MIT. Consulta LICENSE para obtener más información.