🎯 MCP Hunter

MCP-сервер (Model Context Protocol) для OSINT, активной разведки, веб-поиска, глубокого скрейпинга и обогащения данных о компаниях и людях.

MCP Hunter подключает ИИ-ассистентов (таких как Gemini Antigravity, Claude Desktop, Cursor и Windsurf) напрямую к интернету и открытым источникам данных. Он умеет искать в Google/Web, интеллектуально скрейпить и очищать страницы, извлекать контакты (email, WhatsApp, телефоны, соцсети) и обогащать профили компаний официальными данными Receita Federal (CNPJ, партнёры/QSA, уставный капитал и адрес).

✨ Основные возможности

• 🔍 Веб-поиск без платных ключей: Быстрый поиск с поддержкой расширенных операторов (site:, inurl:, filetype:) и региональной ориентацией на Бразилию (br-pt).

• 🌐 Интеллектуальный скрейпинг и очистка контента: Использует trafilatura и BeautifulSoup для извлечения только основного текста, удаляя рекламу, меню и код.

• 📞 Хирургический экстрактор контактов: Алгоритмы Regex и эвристики для определения:

  • Действительных email-адресов (с фильтром от спама и изображений);

  • Стационарных и мобильных телефонов в бразильском формате;

  • Прямых ссылок WhatsApp (wa.me/ и api.whatsapp.com);

  • Официальных профилей в соцсетях (Instagram, LinkedIn, Facebook, X/Twitter, YouTube, TikTok, GitHub);

  • Номеров CNPJ с математической проверкой контрольных цифр.

• 🏛️ Официальный запрос в Receita Federal (BrasilAPI): Получает юридическое наименование, торговое наименование, регистрационный статус, дату открытия, уставный капитал, основной вид деятельности (CNAE), адрес и список партнёров и администраторов (QSA).

• 🏢 Мастер-режим (hunt_company): Принимает название компании и выполняет комплексное расследование 360º от начала до конца за считанные секунды.

• 👤 Расследование по людям (hunt_person): Сканирует публичные упоминания, профили LinkedIn и статьи о человеке.

Related MCP server: LeadSpark MCP

🛠️ Доступные инструменты (Tools)

🚀 Установка и запуск

Этот проект использует сверхбыстрый менеджер пакетов uv.

1. Клонирование репозитория

git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"

2. Автоматическая установка зависимостей

uv sync

3. Запуск автоматических тестов

uv run python tests/test_tools.py

4. Запуск MCP-сервера (режим stdio)

uv run mcp-hunter

🔌 Настройка в MCP-клиентах

Antigravity / Claude Desktop / Cursor / Windsurf

Добавьте приведённую ниже конфигурацию в свой файл конфигурации MCP (claude_desktop_config.json или аналогичный):

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

📂 Структура проекта

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

📄 Лицензия

Распространяется под лицензией MIT. См. LICENSE для получения дополнительной информации.