mcp-virusTotal-threat-analysis

VirusTotal MCP Server integrates VirusTotal data retrieval with Model Context Protocol (MCP) to provide threat intelligence analysis for files, IPs, domains, and URLs. You can query a file hash (MD5/SHA-1/SHA-256), an IP address, a domain, or a URL, and the server will fetch VirusTotal results and feed the data into an embedded AI-assisted analysis workflow to offer actionable remediation suggestions. This enables rapid enrichment of threat intel and helps drive triage decisions within automated workflows or security operations.

To use it, install and run the MCP server as described in the installation section. Once the server is running, you can send queries through MCP clients (for example, from your SIEM, SOC tooling, or other MCP-instrumented clients). Typical interactions include querying a file hash to obtain the VT analysis report, checking IP and domain reputations, or scanning a URL. The system returns VirusTotal JSON responses alongside secondary AI-augmented insights to help with containment, investigation, and response planning. The tools supported by this server include: file hash reports, IP address reports, domain reports, and URL reports, all accessible via MCP calls and augmented by AI-driven interpretation and suggested actions.

Prerequisites:

• Python 3.7+ installed on your system
• VirusTotal API key (obtainable from VirusTotal account dashboard)
• Network access to VirusTotal API endpoints

Step 1: Set up a Python environment

# Optional: create and activate a virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

Step 2: Install dependencies

pip install uv requests

Step 3: Prepare your VirusTotal API key

• Obtain your API key from VirusTotal account settings.
• Set it as an environment variable (recommended):

# Linux/macOS
export VIRUSTOTAL_API_KEY=your_api_key_here
# Windows (PowerShell)
$Env:VIRUSTOTAL_API_KEY = "your_api_key_here"

Step 4: Run the MCP server

# Start the server (the handler is virusTotalServer.py as per the repository README)
python virusTotalServer.py

Step 5: (Optional) Verify functionality

• Use a MCP client to send queries for a file hash, IP, domain, or URL and confirm you receive VirusTotal responses and AI-assisted analysis.

Notes:

• If you prefer to run within uv (uvx) environment, you can adapt the commands to your setup, but Python invocation remains the same for this server.
• Keep API keys secure; do not hard-code keys in source files.

Tips and common issues:

• Ensure your VirusTotal API key has the required permissions and that you’re within your quota limits.
• Do not expose the API key in public repositories; use environment variables or a secure secrets management solution.
• If you hit rate limits, consider staggering queries or upgrading your VirusTotal plan.
• The server’s MCP integration assumes the query payloads align with MCP requests for file hashes, IPs, domains, and URLs. If you extend to additional data types, update the handler accordingly.
• When deploying in production, consider containerization (e.g., Docker) or orchestration for reliability and scaling, and maintain secure storage for API keys.