🎯 MCP Hunter

MCP Server (Model Context Protocol) for OSINT, Active Prospecting, Web Search, Deep Scraping, and Data Enrichment of Companies and People.

MCP Hunter connects AI assistants (such as Gemini Antigravity, Claude Desktop, Cursor, and Windsurf) directly to the internet and open data sources. It can search Google/Web, intelligently scrape and clean pages, extract contacts (emails, WhatsApp, phone numbers, social media), and enrich company profiles with official Receita Federal data (CNPJ, Partners/QSA, Share Capital, and Address).

✨ Main Features

• 🔍 Web Search Without Paid Keys: Fast search with support for advanced operators (site:, inurl:, filetype:) and regional focus on Brazil (br-pt).

• 🌐 Smart Content Scraping and Cleaning: Uses trafilatura and BeautifulSoup to extract only the main text, removing ads, menus, and code.

• 📞 Surgical Contact Extractor: Regex algorithms and heuristics to identify:

  • Valid emails (with anti-spam and anti-image filtering);

  • Landline and mobile numbers in the Brazilian format;

  • Direct WhatsApp links (wa.me/ and api.whatsapp.com);

  • Official social media profiles (Instagram, LinkedIn, Facebook, X/Twitter, YouTube, TikTok, GitHub);

  • CNPJ numbers with mathematical validation of check digits.

• 🏛️ Official Receita Federal Query (BrasilAPI): Retrieves Legal Name, Trade Name, Registration Status, Opening Date, Share Capital, Primary Activity (CNAE), Address, and Board of Partners and Administrators (QSA).

• 🏢 Master Mode (hunt_company): Takes a company name and runs the end-to-end 360º investigation in seconds.

• 👤 People Investigation (hunt_person): Scans public mentions, LinkedIn profiles, and articles about a person.

Related MCP server: LeadSpark MCP

🛠️ Exposed Tools

🚀 Installation and Execution

This project uses the ultra-fast package manager uv.

1. Clone the repository

git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"

2. Install dependencies automatically

uv sync

3. Run the automated tests

uv run python tests/test_tools.py

4. Start the MCP server (stdio mode)

uv run mcp-hunter

🔌 Configuration in MCP Clients

Antigravity / Claude Desktop / Cursor / Windsurf

Add the configuration below to your MCP configuration file (claude_desktop_config.json or similar):

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

📂 Project Structure

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

📄 License

Distributed under the MIT license. See LICENSE for more information.