🎯 MCP Hunter

MCP-Server (Model Context Protocol) für OSINT, aktive Prospektion, Websuche, Deep Scraping und Anreicherung von Unternehmens- und Personendaten.

Der MCP Hunter verbindet KI-Assistenten (wie Gemini Antigravity, Claude Desktop, Cursor und Windsurf) direkt mit dem Internet und offenen Datenquellen. Er kann im Google/Web suchen, Seiten intelligent scrapen und bereinigen, Kontakte extrahieren (E-Mails, WhatsApp, Telefonnummern, soziale Netzwerke) und Unternehmensprofile mit offiziellen Daten der Receita Federal anreichern (CNPJ, Gesellschafter/QSA, Stammkapital und Adresse).

✨ Wichtigste Funktionen

• 🔍 Websuche ohne kostenpflichtige Schlüssel: Schnelle Suche mit Unterstützung für erweiterte Operatoren (site:, inurl:, filetype:) und regionalem Fokus auf Brasilien (br-pt).

• 🌐 Intelligentes Scraping und Bereinigen von Inhalten: Verwendet trafilatura und BeautifulSoup, um nur den Haupttext zu extrahieren und Anzeigen, Menüs und Code zu entfernen.

• 📞 Chirurgischer Kontakt-Extraktor: Regex-Algorithmen und Heuristiken identifizieren:

  • Gültige E-Mails (mit Anti-Spam- und Anti-Bild-Filter);

  • Festnetz- und Mobiltelefonnummern im brasilianischen Format;

  • Direkte WhatsApp-Links (wa.me/ und api.whatsapp.com);

  • Offizielle Profile in sozialen Netzwerken (Instagram, LinkedIn, Facebook, X/Twitter, YouTube, TikTok, GitHub);

  • CNPJ-Nummern mit mathematischer Validierung der Prüfziffern.

• 🏛️ Offizielle Abfrage bei der Receita Federal (BrasilAPI): Liefert Firmenname, Fantasiename, Registrierungsstatus, Gründungsdatum, Stammkapital, Haupttätigkeit (CNAE), Adresse und das Verzeichnis der Gesellschafter und Geschäftsführer (QSA).

• 🏢 Master-Modus (hunt_company): Nimmt den Namen eines Unternehmens entgegen und führt die komplette 360°-Untersuchung in Sekundenschnelle durch.

• 👤 Personenrecherche (hunt_person): Durchsucht öffentliche Erwähnungen, LinkedIn-Profile und Artikel über eine Person.

Related MCP server: LeadSpark MCP

🛠️ Bereitgestellte Tools

🚀 Installation und Ausführung

Dieses Projekt nutzt den ultraschnellen Paketmanager uv.

1. Repository klonen

git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"

2. Abhängigkeiten automatisch installieren

uv sync

3. Automatisierte Tests ausführen

uv run python tests/test_tools.py

4. MCP-Server starten (Stdio-Modus)

uv run mcp-hunter

🔌 Konfiguration in den MCP-Clients

Antigravity / Claude Desktop / Cursor / Windsurf

Fügen Sie die folgende Konfiguration in Ihre MCP-Konfigurationsdatei (claude_desktop_config.json oder ähnlich) ein:

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

📂 Projektstruktur

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

📄 Lizenz

Verteilt unter der MIT-Lizenz. Siehe LICENSE für weitere Informationen.