w0h1v/mcp-virustotal

Tools ·
HTTP ·
Security ·
Troubleshooting ·
Docs
**mcp-virustotal** is an MCP server that gives AI agents access to the VirusTotal v3 API. Hand your agent a hash, URL, IP or domain and get back the detection report plus the relationships an analyst would pivot on: contacted hosts, dropped files, resolutions, threat actors.
> [!NOTE]
> Independent project, not affiliated with VirusTotal or Google. You need your own VirusTotal API key.
Highlights
- **Reports with relationships.** File, URL, IP and domain reports fetch key relationships in one batched ?relationships= call to save quota.
- **Cache first.** get_url_report returns the cached VirusTotal report and only submits a scan on a cache miss.
- **Pivot tools.** Corpus search with VTI-style modifiers (type:peexe positives:5+), merged sandbox behaviour summaries, and threat-actor and malware-family collections.
- **Full relationship paging.** 100+ relationship types across files, URLs, IPs and domains, with cursor pagination.
- **Two transports.** stdio for desktop clients, HTTP streaming for a shared service.
- **Tested.** Unit tests for the formatters and API layer run in CI on Node 20, 22 and 24.
How it works
Quickstart
**Requirements:** Node.js 20 or newer and a VirusTotal API key.
For Claude Desktop, VS Code, Smithery and running from source, see Connect a client.
Then ask your agent: *"Look up the SHA-256 275a021bbfb6489e54d471899f7db9d1663fc695ec2fe2a2c4538aabf651fd0f (the EICAR test file) and show what it drops and contacts."*
Tools
Eleven tools. Full parameters and relationship lists are in the tool reference.
| Group | Tools |
|---|---|
| Reports (with relationships) | get_file_report, get_url_report, get_ip_report, get_domain_report |
| Relationship paging | get_file_relationship, get_url_relationship, get_ip_relationship, get_domain_relationship |
| Search and pivot | search_vt, get_file_behaviour_summary, get_collection |
HTTP streaming transport
stdio is the default. Set MCP_TRANSPORT=httpStream to run a standalone HTTP service:
A health check is served at /health.
Environment variables
| Variable | Default | Description |
|---|---|---|
| VIRUSTOTAL_API_KEY | *(required)* | Your VirusTotal API key |
| MCP_TRANSPORT | stdio | stdio or httpStream |
| MCP_HOST | localhost | Bind address (httpStream only). The Docker image sets 0.0.0.0 |
| MCP_PORT | 3000 | HTTP port (httpStream only) |
| MCP_ENDPOINT | /mcp | HTTP endpoint path (httpStream only) |
Security
> [!WARNING]
> The HTTP transport has **no authentication**. Keep the port on localhost or behind an authenticating reverse proxy, or anyone who can reach it can spend your API quota.