VirusTotal MCP Server
Access VirusTotal v3 threat intelligence for files, URLs, IPs, and domains through 11 MCP tools.
Get comprehensive reports for files, URLs, IPs, and domains, including detections, metadata, and key relationships.
Page through relationship types such as contacted domains/IPs, dropped files, redirects, DNS/WHOIS, SSL certificates, subdomains, and threat actors.
Search the VirusTotal corpus with plain IOCs, comments, or VTI-style modifiers, with cursor pagination.
Get merged sandbox behavior summaries for files, including processes, network activity, registry, MITRE ATT&CK, IDS alerts, and signatures.
Retrieve VirusTotal collections for threat actors, malware families, campaigns, intel reports, and IOC sets.
Use URL reports cache-first, submitting a scan only on cache miss.
Run over stdio or HTTP streaming, with an HTTP health check; HTTP transport has no built-in authentication.
Allows querying the VirusTotal API for comprehensive security analysis reports including URL analysis, file analysis, IP analysis, domain analysis, and relationship tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@VirusTotal MCP Server scan the URL https://example.com for malware"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Independent project, not affiliated with VirusTotal or Google. You need your ownVirusTotal 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_reportreturns 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.
Related MCP server: OSINT MCP Server
How it works
flowchart LR
A["AI agent<br/>(Claude, Codex, Gemini, VS Code)"] -->|"MCP over stdio or HTTP"| S["mcp-virustotal"]
S -->|"validate input,<br/>HTTPS + API key"| V["VirusTotal v3 API"]
V -->|"JSON"| S
S -->|"formatted report text"| AQuickstart
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-virustotalFor Claude Desktop, VS Code 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) |
|
Relationship paging |
|
Search and pivot |
|
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.jsdocker build -t mcp-virustotal .
docker run -p 127.0.0.1:3000:3000 -e VIRUSTOTAL_API_KEY=your-key -e MCP_TRANSPORT=httpStream mcp-virustotalA health check is served at /health.
Environment variables
Variable | Default | Description |
| (required) | Your VirusTotal API key |
|
|
|
|
| Bind address ( |
|
| HTTP port ( |
|
| HTTP endpoint path ( |
Security
The HTTP transport hasno authentication. Keep the port on localhost or behind an authenticating reverse proxy, or anyone who can reach it can spend your API quota.
Tool arguments are validated with zod schemas before any request is built.
The API key is read from the environment and sent only to VirusTotal.
Lookups send your indicators to VirusTotal. A URL scan on a cache miss submits that URL for analysis.
Report vulnerabilities privately; see SECURITY.md.
Troubleshooting
Wrong API key: the key is usually 64 characters with no spaces or quotes. Restart the client after changing config.
429 errors: the public tier allows 4 requests per minute.
Logs:
logs/mcp-virustotal-server.login the package directory.
More in the troubleshooting guide.
Development
git clone https://github.com/w0h1v/mcp-virustotal && cd mcp-virustotal
npm ci
npm test # build + unit tests, no key or network
VIRUSTOTAL_API_KEY=your-key npm run smoke # all 11 tools against the real APIThe smoke test paces calls at 20 s for the public-tier limit and isn't suited to free tiers reduced to a few lookups a day. See CONTRIBUTING.md and the changelog.
License
MIT. See LICENSE.
Available Tools
11 toolsget_collectionA
Retrieve a VirusTotal collection by ID. Collections represent threat actors, malware families, campaigns, intel reports, and curated IOC sets — often referenced from the related_threat_actors and collections relationships on other tools. Optionally include relationships (files, urls, domains, ip_addresses, references, threat_actors, related_collections, related_references, comments, owner, autogenerated_graphs) to fetch member IOCs in the same call.
Inputs: id (required), relationships.
get_domain_relationshipA
Query a specific relationship type for a domain with pagination support. Choose from 24 relationship types including subdomains, resolutions, SSL certificates, WHOIS history, and threat actors. Useful for detailed investigation of specific relationship types.
Inputs: domain (required), relationship (required), limit, cursor.
get_domain_reportA
Get a comprehensive domain analysis report including DNS records, WHOIS data, and key relationships (SSL certificates, subdomains, historical data). Optionally specify which relationships to include in the report. Returns both the basic analysis and relationship data.
Inputs: domain (required), relationships.
get_file_behaviour_summaryA
Get a consolidated sandbox behaviour summary for a file (MD5/SHA-1/SHA-256), merged across every sandbox that analyzed it. Returns processes, files, registry, network activity, MITRE ATT&CK techniques, IDS alerts, and signature matches in a single view — far more useful than iterating individual behaviour reports.
Inputs: hash (required).
get_file_relationshipA
Query a specific relationship type for a file with pagination support. Choose from 40 relationship types including behaviors, network connections, dropped files, embedded content, execution chains, and threat actors. Useful for detailed investigation of specific relationship types.
Inputs: hash (required), relationship (required), limit, cursor.
get_file_reportA
Get a comprehensive file analysis report using its hash (MD5/SHA-1/SHA-256). Includes detection results, file properties, and key relationships (behaviors, dropped files, network connections, embedded content, threat actors). Returns both the basic analysis and automatically fetched relationship data.
Inputs: hash (required).
get_ip_relationshipB
Query a specific relationship type for an IP address with pagination support. Choose from 15 relationship types including communicating files, historical SSL certificates, WHOIS records, resolutions, and threat actors. Useful for detailed investigation of specific relationship types.
Inputs: ip (required), relationship (required), limit, cursor.
get_ip_reportA
Get a comprehensive IP address analysis report including geolocation, reputation data, and key relationships (communicating files, historical certificates/WHOIS, resolutions). Returns both the basic analysis and automatically fetched relationship data.
Inputs: ip (required).
get_url_relationshipA
Query a specific relationship type for a URL with pagination support. Choose from 22 relationship types including communicating files, contacted domains/IPs, downloaded files, redirects, referrers, threat actors, and collections. Useful for paging through the full list when the summary in get_url_report is truncated.
Inputs: url (required), relationship (required), limit, cursor.
get_url_reportA
Get a comprehensive URL analysis report including security scan results and key relationships (communicating files, contacted domains/IPs, downloaded files, redirects, threat actors). Returns the cached VirusTotal report when available, or submits the URL for scanning and waits for results.
Inputs: url (required).
search_vtA
Search the VirusTotal corpus for files, URLs, domains, IPs, or comments matching a query. Accepts plain IOCs (hash, URL, domain, IP), free text against comments, or VTI-style search modifiers like "type:peexe size:90kb+ tag:signed positives:5+". Paginated via cursor.
Inputs: query (required), limit, cursor.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource and action: reports for comprehensive data, relationships for specific paginated queries, collection retrieval, and search. No two tools have overlapping purposes.
All tools follow a consistent verb_noun pattern in snake_case (e.g., get_domain_report, get_file_relationship, search_vt). The slight deviation for get_file_behaviour_summary is still clear and does not break consistency.
With 11 tools covering four entity types (domain, file, IP, URL) plus collection and search, the count is well-scoped for a read-oriented threat intelligence API—not too few, not excessive.
The set provides comprehensive coverage: for each entity there is a report and a relationship query, plus search and collection retrieval. Missing create/update/delete are expected for a read-only API; optional submission for URLs is handled.
Maintenance
Related MCP Connectors
Official VirusTotal MCP server: threat reports, file and URL submissions, and analysis recovery.
VirusTotal MCP — file / URL / domain / IP reputation (BYO key)
MCP server for ScanMalware.com URL scanning, malware detection, and analysis.
Security scanner for MCP servers. Detect vulnerabilities, prompt injection, and tool poisoning.
Related MCP Servers
FlicenseNot gradedqualityDmaintenanceMCP server that provides tools for interacting with the Fluidattacks API-- AlicenseDqualityDmaintenanceA comprehensive MCP server providing tools for IP, domain, email, and image-based open-source intelligence. It integrates services like Shodan, VirusTotal, and HaveIBeenPwned to facilitate advanced security research and data gathering.56MIT
- FlicenseAqualityDmaintenanceMCP server for security analysis using VirusTotal API, enabling AI assistants to analyze URLs, files, IP addresses, and domains with automatic relationship fetching.81-
- AlicenseCqualityDmaintenanceA Model Context Protocol (MCP) server that enables LLMs to interact with the VirusTotal API for malware analysis, URL scanning, and threat intelligence.81MIT