VirusTotal MCP Server

A Model Context Protocol (MCP) server that provides security analysis tools powered by the VirusTotal API v3. Analyse URLs, files, IP addresses and domains directly from your AI assistant.

Quick Start

Claude Desktop (stdio)

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "virustotal": {
      "command": "npx",
      "args": ["-y", "@tocharianou/mcp-virustotal"],
      "env": {
        "VIRUSTOTAL_API_KEY": "<your-api-key>"
      }
    }
  }
}

Get your free API key at virustotal.com.

HTTP / Streamable mode

MCP_TRANSPORT=http MCP_HTTP_PORT=3000 VIRUSTOTAL_API_KEY=<key> npx @tocharianou/mcp-virustotal

Then point your MCP client at http://localhost:3000/mcp.

Features

URL analysis — full scan results, HTTP response details, trackers, redirection chains
File analysis — hash lookup (MD5/SHA-1/SHA-256), sandbox verdicts, YARA/Sigma/IDS results
IP analysis — geolocation, ASN, WHOIS, SSL certificate chain
Domain analysis — DNS records, WHOIS, popularity rankings, threat severity
Relationship traversal — paginated access to all VT relationship types per resource

Configuration

Environment variable	Required	Description
`VIRUSTOTAL_API_KEY`	✓*	VT API key, sent as `x-apikey` header (direct mode)
`VIRUSTOTAL_BASE_URL`	–	Override API base URL (e.g. proxy endpoint)
`VIRUSTOTAL_AUTH_TOKEN`	✓*	Bearer token for proxy authentication
`VIRUSTOTAL_TIMEOUT`	–	Request timeout in ms (default: `30000`)
`MCP_TRANSPORT`	–	`stdio` (default) or `http`
`MCP_HTTP_PORT`	–	HTTP server port (default: `3000`)
`MCP_HTTP_HOST`	–	HTTP server host (default: `localhost`)

* Either VIRUSTOTAL_API_KEY (direct) or VIRUSTOTAL_BASE_URL + VIRUSTOTAL_AUTH_TOKEN (proxy) must be set.

Direct vs Proxy mode

Direct mode — the server calls VirusTotal directly using your own API key:

VIRUSTOTAL_API_KEY=VT_KEY_HERE

Proxy mode — the server calls a backend gateway that injects the real API key and handles billing. The server authenticates to the gateway using a Bearer token:

VIRUSTOTAL_BASE_URL=https://gateway.example.com/vt
VIRUSTOTAL_AUTH_TOKEN=YOUR_BEARER_TOKEN

The tool itself is mode-agnostic; the calling application sets the appropriate variables.

Available Tools

Tool	Description
`get_url_report`	Full URL scan including automatic relationship fetch
`get_url_relationship`	Paginated URL relationship query (17 types)
`get_file_report`	File analysis by hash (MD5/SHA-1/SHA-256)
`get_file_relationship`	Paginated file relationship query (41 types)
`get_ip_report`	IP address analysis with geolocation and relationships
`get_ip_relationship`	Paginated IP relationship query (12 types)
`get_domain_report`	Domain analysis with DNS, WHOIS and relationships

Example Queries

"Check if this URL is malicious: https://example.com"
"Analyse this file hash: d41d8cd98f00b204e9800998ecf8427e"
"What files has IP 8.8.8.8 been communicating with?"
"Give me the SSL certificate history for github.com"

Debugging

Use the MCP Inspector to test and debug:

npm run inspector

Server logs are written to stderr so they do not interfere with the MCP JSON-RPC stream on stdout.

Troubleshooting

Symptom	Likely cause
`No credentials configured`	Neither `VIRUSTOTAL_API_KEY` nor `VIRUSTOTAL_AUTH_TOKEN` is set
`VirusTotal API error: 401`	Invalid or expired API key
`VirusTotal API error: 429`	API quota exceeded (free tier: 500 req/day)
Tool calls time out	Increase `VIRUSTOTAL_TIMEOUT` or check network connectivity

Development

git clone https://github.com/TocharianOU/mcp-virustotal.git
cd mcp-virustotal
npm install --ignore-scripts
npm run build
cp .env.example .env   # fill in your API key
npm start

Release

See RELEASE.md for the full release process.

License

Disclaimer: This project is community-maintained and is not affiliated with or endorsed by VirusTotal or Google LLC.

@tocharianou/mcp-virustotal

Quick Install