HeaderHawk

Provides real-time phishing detection, IoC extraction, and VirusTotal threat intelligence via an MCP endpoint.

python

0

GitHub Stars

python

Language

2 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "nervpeng-headerhawk_mcp": {
      "command": "headerhawk-mcp",
      "args": [],
      "env": {
        "VIRUSTOTAL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

HeaderHawk MCP Server enables real-time email header analysis, phishing indicator detection, and threat intelligence integration through the MCP protocol so security teams can quickly assess and respond to suspicious emails and threats.

How to use

You run the HeaderHawk MCP Server locally and connect to it with an MCP-compatible client to perform phishing analysis, IoC extraction, and threat intelligence lookups. Start by launching the MCP server from the command line or via a container, then use an MCP client to issue standard requests such as analyzing an email, extracting IoCs, or scanning IoCs against VirusTotal. You’ll receive structured results that include email metadata, authentication results, detected indicators, risk level, and recommended actions.

Typical usage patterns you can perform with the MCP client include:

How to install

Prerequisites you need before installing HeaderHawk MCP Server:

Python 3.8 or newer
pip (Python package manager)
VirusTotal API key for threat scanning features

Install HeaderHawk MCP Server from PyPI

pip install headerhawk

Additional setup steps

Configure environment variables and deploy options to enable full MCP functionality.

export VIRUSTOTAL_API_KEY="your_api_key_here"
export VIRUSTOTAL_RATE_LIMIT="4"  # requests per minute
export OUTPUT_FORMAT="json"  # or "text"
export CRITICAL_THRESHOLD="0.8"
export HIGH_THRESHOLD="0.6"

Available tools

say_hello

Test connection status between the MCP client and the HeaderHawk MCP server.

analyze_email

Perform a full phishing analysis on a provided .eml file, including header analysis, indicators, and malware detection.

extract_iocs

Extract indicators of compromise such as URLs, domains, IPs, emails, and attachment metadata from an email.

scan_with_virustotal

Lookup IoCs against VirusTotal and return detection ratios, verdicts, and threat classifications.