MCP Virustotal

Quickstart · 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

flowchart LR
    A["AI agent(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-virustotal"]
    S -->|"validate input,HTTPS + API key"| V["VirusTotal v3 API"]
    V -->|"JSON"| S
    S -->|"formatted report text"| A

Quickstart

Requirements: Node.js 20 or newer and a VirusTotal API key.

# Claude Code
claude mcp add --transport stdio --env VIRUSTOTAL_API_KEY=your-key virustotal -- npx -y @burtthecoder/mcp-virustotal

# Codex CLI
codex mcp add virustotal --env VIRUSTOTAL_API_KEY=your-key -- npx -y @burtthecoder/mcp-virustotal

# Gemini CLI
gemini mcp add -e VIRUSTOTAL_API_KEY=your-key virustotal npx -y @burtthecoder/mcp-virustotal

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:

MCP_TRANSPORT=httpStream MCP_PORT=3000 VIRUSTOTAL_API_KEY=your-key node build/index.js

docker build -t mcp-virustotal .
docker run -p 127.0.0.1:3000:3000 -e VIRUSTOTAL_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-virustotal

A health check is served at /health.

Environment variables