OSINT, 능동적 탐색, 웹 검색, 딥 스크래핑, 기업 및 개인 데이터 보강을 위한 MCP(Model Context Protocol) 서버.
MCP Hunter는 인공지능 어시스턴트(Gemini Antigravity, Claude Desktop, Cursor, Windsurf 등)를 인터넷 및 공개 데이터 소스에 직접 연결합니다. Google/웹 검색, 지능적인 페이지 스크래핑 및 정리, 연락처(이메일, WhatsApp, 전화번호, 소셜 미디어) 추출, 그리고 Receita Federal의 공식 데이터(CNPJ, 주주/QSA, 자본금, 주소)로 기업 프로필을 강화할 수 있습니다.
🔍 유료 키 없이 웹 검색: 고급 연산자(site:, inurl:, filetype:) 지원 및 브라질 지역 설정(br-pt)을 갖춘 빠른 검색.
🌐 지능형 콘텐츠 스크래핑 및 정리: trafilatura와 BeautifulSoup를 사용하여 광고, 메뉴, 코드를 제거하고 본문 텍스트만 추출합니다.
📞 정밀 연락처 추출기: 다음을 식별하기 위한 Regex 알고리즘 및 휴리스틱:
유효한 이메일(스팸 및 이미지 필터 포함);
브라질 형식의 유선전화 및 휴대전화;
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
도구 | 설명 | 주요 매개변수 |
| Web/Google 검색을 수행하여 링크, 제목, 요약 스니펫을 반환합니다. |
|
| 사이트에 접속하여 읽을 수 있는 텍스트를 추출하고 연락처 하위 페이지( |
|
| URL 또는 원시 텍스트를 분석하여 이메일, 전화번호, WhatsApp, 소셜 미디어 및 CNPJ를 추출합니다. |
|
| BrasilAPI / MinhaReceita를 통해 Receita Federal 데이터베이스를 조회합니다. |
|
| 기업 360º 파일: 웹사이트 검색, 연락처, 소셜 미디어, CNPJ 및 주주 구성 추출. |
|
| 특정 인물에 대한 공개 활동, LinkedIn 프로필 및 웹 언급을 조사합니다. |
|
이 프로젝트는 초고속 패키지 관리자 **uv**를 사용합니다.
git clone <URL_DO_REPOSITORIO>
cd "MCP Hunter"uv syncuv run python tests/test_tools.pyuv run mcp-hunterMCP 설정 파일(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 oficialMIT 라이선스에 따라 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.
Consulta dados oficiais de uma empresa brasileira na Receita Federal (BrasilAPI).
Args: cnpj: Número do CNPJ com ou sem pontuação (ex: 00.000.000/0001-91 ou 00000000000191).
Returns: Dossiê cadastral oficial com Razão Social, Sócios (QSA), Capital Social, Endereço e Contatos.
| Name | Required | Description | Default |
|---|---|---|---|
| cnpj | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the data source (BrasilAPI/Receita Federal) and the returned fields, but does not mention error handling for invalid CNPJs, authentication requirements, rate limits, or any auxiliary behavior. This is adequate for a straightforward read-only lookup but leaves some operational unknowns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-organized with a one-line purpose, an Args section, and a Returns section. Every line contributes essential information, and the key purpose statement is front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool, the description covers the essentials: the data source, input format, and the return contents including Razão Social, Sócios (QSA), Capital Social, Endereço, and Contatos. Minor gaps like handling of invalid CNPJs and explicit sibling differentiation are absent, but overall the agent has enough context to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only the parameter name 'cnpj' with no description (0% schema coverage). The description compensates fully by explaining the accepted format and giving two concrete examples: '00.000.000/0001-91' and '00000000000191'. This is exactly the semantic detail an agent needs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Consulta dados oficiais de uma empresa brasileira na Receita Federal (BrasilAPI)'. This precisely identifies the tool's function and scope, and inherently distinguishes it from the sibling tools (scrape_website, hunt_person, etc.) which target different tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly establishes the use case: retrieving official Brazilian company data from a CNPJ. It does not explicitly name alternative tools or exclusion conditions, but the unique CNPJ-focused purpose makes the intended context unmistakable, so an agent can infer when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extrai cirurgicamente e-mails, telefones, WhatsApp, redes sociais e CNPJs de uma URL ou texto.
Args: url: URL do site a ser vasculhado (opcional se 'text' for fornecido). text: Texto bruto para análise de entidades (opcional se 'url' for fornecida).
Returns: Relatório estruturado com todos os contatos identificados.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| text | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Não há anotações, então a descrição precisa carregar o peso do comportamento. Ela informa que retorna um relatório estruturado e que url/text são opcionais condicionalmente, mas não aborda casos como ambos fornecidos, nenhum fornecido, ou limitações de acesso/rate-limit ao vasculhar a URL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A descrição é organizada, com seções Args/Returns, e a operação principal vem logo no início. O termo 'cirurgicamente' é estilístico e desnecessário, mas não prejudica a clareza nem adiciona ruído relevante.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Para uma ferramenta simples de dois parâmetros com output schema presente, a descrição cobre o essencial: o que faz, as entradas e o tipo de retorno. Faltam apenas detalhes de borda como precedência quando url e text são enviados juntos, mas isso não compromete gravemente o uso.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Com cobertura de schema em 0%, a descrição compensa bem ao definir cada parâmetro e sua relação de opcionalidade ('url é opcional se text for fornecido' e vice-versa). Isso adiciona significado real ao que o schema não documenta.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
A descrição usa verbo específico ('Extrai'), recurso claro ('e-mails, telefones, WhatsApp, redes sociais e CNPJs') e fonte ('URL ou texto'), diferenciando-se bem de ferramentas irmãs como scrape_website ou hunt_person.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
A descrição deixa claro o contexto de uso: fornecer uma URL ou texto bruto para extração de contatos. Porém, não explicita quando não usar a ferramenta nem a compara com alternativas, deixando a decisão principalmente por inferência.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dossiê 360º de Empresa: busca site oficial, extrai contatos, redes sociais, CNPJ e sócios.
Args: company_name: Nome da empresa ou marca. domain_or_url: Site oficial da empresa (se já souber, agiliza a busca).
Returns: Dossiê de inteligência completo sobre a empresa.
| Name | Required | Description | Default |
|---|---|---|---|
| company_name | Yes | ||
| domain_or_url | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden and does disclose the core behavior: searching an official site and extracting contacts, social media, CNPJ, and partners. However, it does not mention limitations, data reliability, or whether this is purely a read-only web intelligence operation, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly organized with a one-line summary followed by Args and Returns sections. Every sentence adds value and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is largely complete for invocation: inputs are explained, returns are summarized, and an output schema exists for a full dossier. The main gap is the lack of guidance around when to choose this tool instead of related siblings, which matters given the tool set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains company_name as company or brand name, and domain_or_url as the official site that speeds up the search when already known. Both parameters receive meaningful semantics beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource: it states it builds a 360-degree company dossier by searching the official website, extracting contacts, social media, CNPJ, and partners. This clearly distinguishes it from siblings like scrape_website or consult_cnpj, which cover only a single aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance is provided relative to sibling tools. The only usage hint is that providing domain_or_url speeds up the search, but it never explains when to choose hunt_company over extract_contacts, consult_cnpj, or hunt_person.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pesquisa na Web/Google retornando links, títulos e resumos.
Args: query: Termo de busca (aceita operadores como site:, inurl:, etc.). max_results: Quantidade máxima de resultados (1 a 20). region: Região da busca (ex: 'br-pt' para Brasil, 'wt-wt' para global).
Returns: Lista formatada em Markdown com os resultados encontrados.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| region | No | br-pt | |
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It conveys that this is a read-only search and describes the Markdown return format, but does not disclose potential rate limits, failure behavior, authentication needs, or region restrictions beyond examples. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one purpose sentence, then Args, then Returns. Every line earns its place with no repetition of schema defaults or generic filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter search tool with an output schema, the description covers purpose, parameter semantics, and return format sufficiently. It lacks explicit exclusions or edge-case guidance, but nothing essential for a basic correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add parameter meaning. It does: query accepts operators, max_results ranges from 1 to 20, and region includes concrete examples like 'br-pt' and 'wt-wt'. This compensates well for the empty schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Pesquisa na Web/Google') and output (links, titles, summaries). This clearly distinguishes hunter_search from siblings like scrape_website or extract_contacts, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the intended context explicit — generic web/Google search — and even documents advanced query operators. It does not explicitly exclude alternatives or say when not to use it, but the sibling tools are clearly different enough that the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Investiga a presença pública de uma pessoa (LinkedIn, cargos, menções e notícias).
Args: name: Nome completo da pessoa. context: Contexto adicional (empresa onde trabalha, cidade, cargo, etc.).
Returns: Resumo de perfis e menções públicas encontradas.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| context | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reveal that the tool scans public sources and returns a summary of profiles and mentions. It does not, however, disclose limits on result freshness, potential inaccuracies, or any access-related behavior, which would matter for correct interpretation of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence summary leads, followed by concise Args and Returns sections. Every sentence adds useful information, with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Considering the simple two-parameter schema and the presence of an output schema, the description supplies enough to invoke the tool correctly: it states the exact inputs and the shape of the outcome. It stops short of being complete because it offers no guidance on choosing this tool among the five siblings, but that gap is shared with the usage-guidelines dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add all parameter meaning, and it does: 'name' is clearly specified as Nome completo da pessoa and 'context' is explained with concrete examples (empresa, cidade, cargo). This fully compensates for the absent schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Investiga') with a clear resource ('presença pública de uma pessoa') and enumerates concrete data sources (LinkedIn, cargos, menções e notícias). This makes the tool's purpose immediately clear and distinguishes it from siblings like hunt_company, which targets organizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the tool's purpose — it should be used for investigating a person's public presence. However, it does not explicitly say when to prefer this over hunt_company, hunter_search, or extract_contacts, and gives no exclusions or alternative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Acessa um site, remove lixo/anúncios e extrai o texto legível e subpáginas de contato.
Args: url: URL completa do site (ex: https://empresa.com.br). deep_contacts: Se True, vasculha também páginas internas como /contato e /sobre.
Returns: Texto limpo e estruturado extraído da página.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| deep_contacts | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses meaningful behavior: it cleans the page, extracts readable text, and optionally crawls internal pages such as /contato and /sobre. However, it does not mention limitations like JavaScript-rendered pages, potential blocking, rate limits, or the exact meaning of 'subpáginas de contato'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-organized with Args and Returns sections. The phrase 'subpáginas de contato' is slightly awkward and could be clearer, but overall it is efficient and front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the key parameters and return type well for a two-parameter tool, and the presence of an output schema reduces the need to describe return values. However, it lacks guidance on when to use the tool versus siblings, and the contact-subpage behavior is ambiguous enough that an agent may not know exactly what will be returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining both parameters. It gives an example URL format and clearly defines the deep_contacts behavior, including which kind of internal pages are scanned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool accesses a website, removes ads/junk, and extracts readable text and contact subpages. It distinguishes the tool from contact-only extraction by emphasizing the text-scraping behavior, but it does not explicitly contrast it with siblings like extract_contacts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as extract_contacts or hunt_company. It explains what the tool does but never states when it should be preferred, when it should not be used, or which sibling covers other cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0consult_cnpjextract_contactshunt_companyhunt_personhunter_searchscrape_websiteScored across 6 tools
Most tools have distinct purposes, but scrape_website, extract_contacts, and hunt_company overlap when the goal is finding contact information from a URL. The descriptions help clarify scope, but an agent could still be uncertain whether to scrape, extract, or run a full company dossier.
Five of six tools follow a consistent verb_noun pattern in snake_case (scrape_website, extract_contacts, hunt_company, hunt_person, consult_cnpj). hunter_search breaks the pattern by using the agent-noun 'hunter' instead of the verb 'hunt'.
Six tools is well-scoped for an OSINT/company-research server. It covers search, scraping, contact extraction, company/person investigation, and official CNPJ lookup without unnecessary bloat or feeling too thin.
The set covers the core intelligence workflow: search, scrape, extract contacts, investigate companies/people, and consult official records. Minor gaps exist, such as no explicit reverse-lookup or export/verification tool, but the main workflows do not hit dead ends.
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
AI, X and web search, page extraction, X data, People Search, and Company Search.
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
Direct access to 60+ scraping and search tools. Extract structured data from Google (Search, Maps, Trends), Amazon, Airbnb, Social Media, and any web page directly into your AI agent.